API가 실제로 무엇인가

API를 생각하는 가장 깔끔한 방법은 한 프로그램이 다른 프로그램에게 제공하는 요청들의 메뉴라고 보는 것이다.

식당은 당신이 주방에 들어와 요리하게 해주지 않는다. 메뉴판을 건넨다. 여기 주문할 수 있는 것들이 있고, 이렇게 주문하면 되고, 이런 걸 받게 된다고 알려준다. 주방이 어떻게 돌아가는지 알 필요는 없다. 메뉴판만 있으면 된다. API가 정확히 그것이다 — 회사가 "우리 서비스에 할 수 있는 요청들은 이것이고, 각각이 무엇을 돌려주는지 알려드립니다"라고 말하는 것이다.

AI가 "날씨 API를 호출하는" 코드를 쓸 때, 그건 그 메뉴에서 주문을 넣는 것이다. 이 도시의 예보를 줘. 날씨 회사의 서버가 일을 처리하고 답을 돌려준다. 당신의 앱은 그들의 데이터베이스나 코드를 절대 보지 못한다. 그냥 요리만 받는다.

   ┌────────────┐   요청: GET /forecast?city=London   ┌────────────┐
   │   내 앱    │ ──────────────────────────────────▶ │    API     │
   │(클라이언트)│                                     │ 엔드포인트 │
   │            │ ◀────────────────────────────────── │   (서버)   │
   └────────────┘   응답: { "temp": 14, ... } (JSON)  └────────────┘
      메뉴에서                                  일을 처리하고,
      주문한다                                  요리를 보낸다

중요한 사고방식의 전환이 있다. API는 계약이다. 상대 회사는 당신이 특정한 방식으로 요청하면 특정한 모양의 답을 받게 될 거라고 약속한다. 당신의 일 — 그리고 AI의 일 — 은 올바르게 요청하고 답을 올바르게 읽는 것이다. 대부분의 API 버그는 어느 한쪽이 그 계약을 깨뜨리는 것이다.