[SW Eng] API와 계약 — REST·GraphQL·스키마로 서비스가 대화하는 법

REST API는 자원(경로) 과 행위(HTTP 메서드) 의 조합으로 표현합니다.

GET    /orders        주문 목록 조회      (안전·멱등: 여러 번 호출해도 같음)
POST   /orders        새 주문 생성        (호출마다 새로 생김)
GET    /orders/42     42번 주문 조회
PATCH  /orders/42     42번 주문 일부 수정
DELETE /orders/42     42번 주문 삭제      (멱등: 여러 번 = 결과 같음)

요청/응답은 보통 JSON:
  요청 Body:  {"productId": 7, "qty": 2}
  응답 Body:  {"orderId": 42, "status": "created"}

핵심 규약: GET은 데이터를 바꾸지 않는다(안전), 같은 요청을 여러 번 해도 결과가 같아야 하는 것이 멱등성(요구사항 정의의 중복 처리와 연결). HTTP 상태코드(200/201/400/404/500…)로 결과를 알립니다 — 깊은 코드 해석은 용어사전·networking 트랙에서.

개발 조직의 역할에서 본 'FE↔BE 인터페이스'가 바로 API 계약입니다. 계약은 다음을 정합니다.

계약(예: OpenAPI 명세):
  엔드포인트:  POST /orders
  요청 스키마:  { productId: number(필수), qty: number(필수, ≥1) }
  응답 스키마:  { orderId: number, status: "created"|"failed" }
  에러 형식:   { code: string, message: string }  (예: 400, 409)

계약을 먼저 합의하면:

• FE는 그 계약으로 목(mock) 서버를 띄워 화면을 병렬 개발
• BE는 그 계약에 맞춰 구현
• 둘이 만나는 지점에서 어긋남이 최소화

도구: OpenAPI(Swagger) 명세로 계약을 코드처럼 관리하고, 스키마 검증(JSON Schema) 으로 요청/응답이 계약을 지키는지 자동 확인합니다. 계약이 문서로 고정되면 "그 API 어떻게 생겼죠?"라는 소모적 질문이 사라집니다.

"필드 삭제는 breaking, 추가는 안전" — 계약 관리의 첫 규칙이지만, 실무의 사고는 이 규칙의 회색지대에서 납니다.

• 추가가 안전한 건 소비자가 관대할 때뿐입니다: 모르는 필드를 무시하는 클라이언트(tolerant reader)에겐 필드 추가가 무해하지만, 알 수 없는 필드를 만나면 역직렬화를 거부하도록 엄격하게 설정된 클라이언트는 '안전한 추가'에도 깨집니다. 계약에는 스키마만이 아니라 "모르는 필드는 무시한다" 같은 소비 규칙까지 합의돼야 합니다.
• enum 확장은 사실상 breaking입니다: 응답의 상태값 목록에 새 값을 추가하면, 그 값을 모르는 클라이언트의 분기(switch)가 미정의 경로로 빠집니다. 필드를 지우지 않았어도 클라이언트가 죽습니다. enum이 있는 계약엔 "알 수 없는 값이 오면 이렇게 처리한다"는 폴백 조항이 필요합니다.
• 스키마 diff는 문법만 봅니다: CI의 OpenAPI 호환성 검사는 필드 유무·타입 변화는 잡지만, amount의 단위가 원에서 센트로 바뀌는 것 같은 의미 변화는 통과시킵니다. 이를 보완하는 것이 소비자 주도 계약 테스트(consumer-driven contract, Pact류)입니다 — 각 소비자가 "내가 실제로 쓰는 필드와 기대값"을 계약으로 등록하고, 공급자 CI가 그 기대를 검증합니다. 부수 효과로 '아무도 안 쓰는 필드'가 드러나 자유롭게 정리할 수 있게 됩니다.
• /v2의 숨은 비용은 v1입니다: 버전을 올리는 건 쉽지만, 옛 버전이 살아 있는 한 그것은 별도의 제품입니다 — 보안 패치·모니터링·문서·테스트가 전부 이중화됩니다. 버전별 호출량 계측(누가 아직 v1을 쓰나) 없이 버전을 늘리면, 몇 년 뒤 '끌 수 없는 v1'이 유지보수의 절반을 먹습니다.