API 란 프로그램과 프로그램이 소통하는 창구다. 이 한 문장이 핵심이다. 그리고 이 창구를 어떻게 설계하느냐가 REST API, 그 설계를 파이썬으로 빠르게 구현하는 도구가 FastAPI다. 세 개념은 따로 외울 필요가 없다. 하나의 흐름으로 이해하면 된다.
이 글에서는 API 란 무엇인지 개념부터 시작해, REST API가 왜 필요한지, FastAPI로 무엇을 만들 수 있는지까지 엔지니어의 언어로 풀어낸다.
API 란 — 내부 구조를 몰라도 결과를 받는 구조
F1 레이스에서 이런 상황을 상상해보자. 드라이버는 스티어링 휠의 버튼 하나로 피트월에 타이어 교체를 요청한다. 피트월 엔지니어가 어떤 무선 채널을 쓰는지, 타이어 창고의 재고 시스템이 어떻게 돌아가는지 드라이버는 전혀 모른다. 버튼을 누르면 다음 랩에 타이어가 교체된다. 그게 전부다.
API 란 정확히 이 구조다. 내부가 어떻게 돌아가든 상관없이, 정해진 방식으로 요청하면 결과가 돌아온다.
ATM으로 보면 더 직관적이다. 카드를 넣고 금액을 입력하면 현금이 나온다. 은행 서버가 어느 DB에 접근하는지, 잔액 확인 로직이 어떻게 구현됐는지 우리는 모른다. 그냥 요청하면 결과가 나온다.
사용자 입력 (카드 + 금액)
↓
Request → API (ATM 인터페이스)
↓
서버 내부 처리 (잔액 조회 · 승인)
↓
Response → 결과 반환 (현금 출금)
이 Request → 처리 → Response 사이클이 API의 전부다. 내부 구조를 숨기고, 정해진 입구와 출구만 열어두는 것이 API의 핵심이다.
현장 엔지니어 관점에서 비슷한 구조가 있다. 장비의 바이브코딩 자동화 도구를 붙일 때, 장비 내부 로직을 몰라도 지정된 인터페이스로 명령을 보내면 장비가 응답한다. API가 소프트웨어에서 하는 역할과 본질적으로 같다.
REST API 란 — URL과 HTTP 메서드로 설계하는 약속
API가 “소통 창구”라면, REST는 그 창구를 어떻게 만들지에 대한 약속이다.
ATM 비유를 이어가자. 어느 은행 ATM을 가도 카드 투입구 위치, 버튼 배열, 화면 순서가 비슷하다. 표준이 있기 때문이다. REST API가 바로 그 표준이다.
REST의 핵심 규칙은 하나다. URL은 자원(명사)으로, HTTP 메서드는 행동(동사)으로 구분한다.
| HTTP 메서드 | 의미 | ATM 비유 |
|---|---|---|
| GET | 데이터 조회 | 잔액 조회 |
| POST | 데이터 생성 | 계좌 신규 개설 |
| PUT | 데이터 수정 | 계좌 정보 변경 |
| DELETE | 데이터 삭제 | 계좌 해지 |
계좌 잔액을 조회하는 REST API 란 이런 모습이다.
GET /accounts/123456
→ 123456 계좌의 정보를 가져와라
URL은 “무엇을”, 메서드는 “어떻게 할 것인지”를 담당한다. 이 약속 덕분에 API 구조가 직관적이고, 처음 보는 사람도 의도를 즉시 파악할 수 있다.
반대로 REST 규칙을 어기면 어떻게 될까. /getAccount, /deleteAccountById, /createNewUser 같은 URL이 난립하고, 규칙이 없으니 팀마다 제각각이다. 협업이 어려워지는 건 시간문제다. REST API 란 그 혼란을 막는 설계 표준이다.
FastAPI 란 — 파이썬으로 REST API를 빠르게 만드는 도구
FastAPI 란 파이썬으로 REST API 서버를 빠르게 구축할 수 있는 프레임워크다.
프레임워크란 API 서버를 처음부터 다 짜지 않아도 되도록 뼈대를 미리 제공해주는 도구다. ATM으로 치면, ATM 기계 본체(하드웨어, 화면, 네트워크 연결)는 이미 다 만들어져 있고, 개발자는 “잔액 조회 버튼을 누르면 이 로직을 실행해라”는 부분만 작성하면 되는 구조다.
코드로 보면 이렇다.
from fastapi import FastAPI
app = FastAPI()
@app.get("/accounts/{account_id}")
def get_account(account_id: str):
# account_id로 잔액 조회하는 로직
return {"account_id": account_id, "balance": 150000}
URL /accounts/123456으로 GET 요청이 들어오면, account_id에 123456이 자동으로 들어오고 결과를 Response로 돌려준다. 복잡한 라우팅 설정, 요청 파싱, 에러 처리를 FastAPI가 알아서 처리한다.
FastAPI가 특히 유용한 이유를 정리하면 이렇다.
| 특징 | 내용 |
|---|---|
| 빠른 속도 | 파이썬 프레임워크 중 최상위권 처리 속도 |
| 자동 문서화 | /docs 접속하면 API 명세서 자동 생성 |
| 파이썬 친화적 | 데이터 분석에 이미 파이썬을 쓴다면 진입장벽이 낮음 |
| 타입 검증 | 입력값 형식이 틀리면 자동으로 에러 반환 |
엔지니어 입장에서 특히 주목할 포인트는 자동 문서화다. /docs에 접속하면 Swagger UI가 열리고, 내가 만든 API의 URL, 파라미터, 응답 형식이 자동으로 정리되어 있다. 팀에 API 명세를 따로 작성해서 공유할 필요가 없다.
세 개념이 연결되는 순간 — 엔지니어의 다음 단계
세 개념의 관계를 한 줄로 정리하면 이렇다.
API → 프로그램 간 소통 창구 (개념)
REST API → 그 창구를 URL + HTTP로 설계하는 방식 (규칙)
FastAPI → 파이썬으로 REST API를 빠르게 만드는 도구 (구현)
개념에서 규칙으로, 규칙에서 구현으로 이어지는 흐름이다.
엔지니어가 파이썬으로 데이터를 분석하다 보면 자연스럽게 이런 질문이 생긴다. “이 분석 결과를 다른 시스템과 연동하려면 어떻게 해야 하지?” 혹은 “내가 만든 모델을 팀원이 쓸 수 있게 하려면?” 그 질문의 답이 REST API이고, 그걸 가장 빠르게 구현하는 도구가 FastAPI다.
데이터를 다루는 엔지니어가 FastAPI를 배우는 건 단순히 기능을 하나 추가하는 일이 아니다. 분석 결과를 혼자 보는 것에서 다른 시스템·사람과 연결하는 구조로 바뀌는 전환점이다. 엔지니어가 코딩을 배워야 하는 이유도 결국 이 지점에서 만난다.
핵심 요약
- API 란 내부 구조를 몰라도 정해진 방식으로 요청하면 결과를 받는 프로그램 간 소통 창구다
- REST API 란 URL을 자원(명사)으로, HTTP 메서드를 행동(동사)으로 구분하는 API 설계 약속이다
- FastAPI 란 파이썬으로 REST API 서버를 빠르게 만드는 프레임워크다
- 세 개념은 개념 → 규칙 → 구현의 흐름으로 연결된다
- 파이썬으로 데이터를 다루는 엔지니어에게 FastAPI는 분석 결과를 다른 시스템과 연결하는 자연스러운 다음 단계다
[링크 제안]
API를 이해했다면, 이걸 실제 코드로 어떻게 구조화할지가 다음 질문이다.
프롬프트 엔지니어링으로 AI에게 원하는 결과를 뽑아내는 법도 함께 읽어두면 좋다.
토니 스타크의 garage에서 Agentic Engineering을 읽다
