엔지니어가 API의 개념 오해를 바로잡아 JSON 응답을 API 자체와 구분하고 API를 통신 규칙으로 재정의

Context

저자는 API를 사용해본 경험이 있었으나 API가 정확히 무엇인지 명확하게 이해하지 못하고 있었다. JSON 응답을 API로 착각하거나, URL과 함수를 구별하지 못하는 등 개념적 혼동이 있었다.

Technical Solution

• API의 정의를 재정의: 한 소프트웨어가 다른 소프트웨어와 정의된 규칙으로 통신하는 방식으로 명확화
• JSON과 API의 역할 분리: JSON은 API가 반환하는 응답 데이터 형식이며, API 자체가 아님을 구분
• API 분류 체계화: Public API, Private API, Partner API로 접근성 범위를 구분하고, REST, SOAP, GraphQL, WebSocket으로 동작 방식을 분류
• HTTP 상태 코드의 역할 명확화: 400(입력 누락), 401(인증 실패), 200(성공) 등으로 요청 결과를 즉시 파악하는 규칙 정립
• 레스토랑 비유 모델: 클라이언트(손님) - API(웨이터) - 서버(주방) 관계를 통해 추상적 개념을 구체화

Key Takeaway

API는 JSON 파일이나 단순 함수가 아니라 통신을 위한 정의된 규칙의 집합이며, 응답 데이터 형식(JSON)과 통신 메커니즘(API) 자체를 구분하는 것이 기초 개념 이해의 핵심이다.