API의 세계

API는 식당의 메뉴판입니다. 뭘 줄 수 있는지 알려줍니다

사실 여러분은 이미 API를 쓰고 있습니다. ChatGPT에 질문하면? OpenAI API를 호출한 것입니다. 날씨를 검색하면? 기상청 API입니다. AI 시대에 API를 모르면 아무것도 만들 수 없습니다. 이 섹션에서 배우는 REST API, JSON, Status Code는 Ch10에서 직접 LLM API를 호출할 때 그대로 쓰입니다.

API(Application Programming Interface) — 프로그램이 다른 프로그램에게 '이런 기능을 쓸 수 있어'라고 알려주는 규격입니다. 식당 메뉴판이 손님에게 '이런 음식 주문 가능합니다'라고 알려주듯이요.

API의 종류는 다양하지만, 현재 웹에서 가장 압도적으로 많이 쓰이는 방식이 REST API입니다. OpenAI, Google, 카카오 등 거의 모든 서비스가 REST API를 제공합니다. REST의 핵심은 단순합니다: '어떤 자원(URL)에 어떤 동작(GET/POST/PUT/DELETE)을 할 것인가' — 이것뿐입니다.

REST(Representational State Transfer) — 가장 널리 쓰이는 API 설계 스타일입니다. URL로 자원을 지정하고, HTTP 메서드로 동작을 정합니다. '메뉴 카테고리별로 정리된 깔끔한 메뉴판'이죠.

Endpoint(엔드포인트) — API의 특정 URL입니다. `/api/users`는 사용자 목록, `/api/posts/1`은 1번 게시글. 메뉴판의 각 메뉴 항목입니다.

HTTP Methods(메서드) — 동작을 지정합니다. • GET = 조회 (메뉴 보기) • POST = 생성 (주문하기) • PUT/PATCH = 수정 (주문 변경) • DELETE = 삭제 (주문 취소)

GraphQL — REST의 대안입니다. 클라이언트가 '필요한 데이터만 골라서' 요청합니다. 뷔페에서 원하는 것만 담는 것과 같습니다. Facebook이 만들었습니다.

Status Code(상태 코드) — 서버의 응답 결과를 숫자로 알려줍니다. • 200 = 성공 ✅ • 404 = 못 찾음 (유명한 에러!) • 500 = 서버 에러 (서버가 고장) • 401 = 인증 안 됨 / 403 = 권한 없음

JSON(JavaScript Object Notation) — API 데이터의 표준 형식입니다. 사람도 읽을 수 있고 기계도 파싱할 수 있습니다. `{"name": "짓친", "level": 5}` 같은 형태입니다.

Header(헤더) — 요청/응답의 '봉투 겉면'입니다. 인증 토큰, 콘텐츠 타입 등 메타 정보가 들어갑니다. Body(바디) — '봉투 안의 편지'입니다. 실제 데이터가 여기에 담깁니다.

Query Parameter — URL 뒤의 `?key=value` 부분입니다. `/api/users?page=2&sort=name` 처럼 필터링, 정렬, 페이지네이션에 씁니다. Path Parameter — URL 경로 안의 변수입니다. `/api/users/42`에서 42가 사용자 ID입니다.

Payload(페이로드) — 전송하는 실제 데이터입니다. POST 요청으로 새 글을 작성할 때, 제목·내용이 페이로드입니다. 택배의 '내용물'과 같습니다.

Webhook(웹훅) — '역방향 API'입니다. 보통은 클라이언트가 서버에 요청하지만, 웹훅은 이벤트가 발생하면 서버가 먼저 알려줍니다. 택배 도착 알림과 같습니다.

이론은 충분합니다. 이제 Python으로 실제 REST API를 호출해봅시다. 아래 코드는 GET으로 데이터를 가져오고, POST로 새 데이터를 생성하는 예제입니다. 이 패턴을 익히면 어떤 API든 호출할 수 있습니다 — 날씨, 번역, 그리고 LLM까지.

import requests
import json

# ── GET: 데이터 조회 ──
res = requests.get("https://jsonplaceholder.typicode.com/users/1")
user = res.json()
print(user["name"])   # → Leanne Graham
print(res.status_code) # → 200 (성공)

# ── POST: 새 데이터 생성 ──
new_post = {
    "title": "AI 학습 일기",
    "body": "오늘 API를 배웠다!",
    "userId": 1
}
res = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,  # Body에 JSON 데이터 담기
    headers={"Content-Type": "application/json"}
)
print(res.status_code) # → 201 (생성 성공!)

새로운 데이터를 서버에 생성할 때 사용하는 HTTP 메서드는?

HTTP 상태 코드 404는 무엇을 의미하는가?

Webhook은 클라이언트가 서버에 요청하는 것이 아니라, 서버가 먼저 알려주는 역방향 API이다

REST와 달리, 클라이언트가 필요한 데이터만 선택해서 요청하는 방식은?

API의 세계