¶ 6권 — API 설계와 관리 원칙 세우기: API 거버넌스
서비스 초기에는 API를 "일단 동작하게" 만드는 것이 우선이다. 하지만 프런트엔드·모바일·파트너사가 동시에 같은 API를 쓰기 시작하면 다음과 같은 문제가 반복된다.
- 응답 형식 불일치
- 에러 형식 혼재
- 버전 업그레이드로 인한 기존 클라이언트 파손
이 책은 완벽한 API 설계 이론이 아니라 작은 조직이 지금 당장 적용할 수 있는 판단 기준을 다음 순서로 다룬다.
- 자원 설계
- 문서화
- 에러 표준화
- 버전 관리
- 거버넌스
¶ REST API 설계 원칙
가장 흔한 실수는 URL을 동사 중심(/getUser)으로 짓는 것이다. 표준적 접근은 URL을 자원(명사)으로 두고 행위는 HTTP 메서드로 표현하는 "리소스 지향 설계"다.
| 동작 | HTTP 메서드 | 응답 |
|---|---|---|
| 목록 조회 | GET |
— |
| 생성 | POST |
201 반환 |
| 전체/부분 수정 | PUT/PATCH |
— |
| 삭제 | DELETE |
204 반환 |
동사가 꼭 필요한 동작은 POST /orders/{id}:cancel 같은 형태로 예외 처리한다. 필드명 표기(JSON은 camelCase, URL 경로는 kebab-case)도 미리 정해 두어야 하며, 판단 기준은 "이미 정해진 표준이 있으면 따르고 없으면 팀 내에서 하나로 정해 문서에 못박는다"는 것이다.
목록 조회는 처음부터 페이지네이션을 염두에 두고 설계해야 나중에 기존 클라이언트를 깨뜨리지 않는다.
¶ OpenAPI(Swagger)로 문서화하기
OpenAPI Specification(OAS)은 HTTP API를 사람과 기계 모두가 이해할 수 있는 언어 독립적 표준 포맷이다. 코드에 애노테이션을 달아 스펙을 자동 생성하는 "코드 우선" 방식은 빠르게 시작하기엔 좋다. 하지만 여러 팀이 함께 설계해야 하는 시점부터는 스펙을 먼저 작성해 프런트엔드·백엔드가 함께 리뷰한 뒤 구현에 들어가는 "계약 우선" 방식이 사고를 줄여준다.
실무 판단 기준은 API 소비 범위에 따라 달라진다.
| API 소비 범위 | 문서화 수준 |
|---|---|
| 내부 전용 소규모 API | 위키 정리 정도 |
| 3개 이상 팀이 소비 | OpenAPI를 정식 산출물로 채택, 코드 리뷰 대상 |
| 외부 파트너 제공 | Swagger UI/Redoc 기반 공개 레퍼런스 필수 |
¶ 에러 응답 표준화
같은 회사 안에서도 에러 형식이 엔드포인트마다 다르면 클라이언트가 API마다 별도 파싱 로직을 짜야 하고 장애 대응 시 로그 분석도 어려워진다. IETF의 RFC 9457(Problem Details)은 type·status·title·detail·instance 필드를 표준화한 포맷을 제시한다. 반드시 그대로 따를 필요는 없지만, 핵심은 "조직 안에서 하나의 형식으로 통일하는 것"이다.
작은 팀을 위한 최소 표준안은 다음 네 가지다.
- 모든 에러를 하나의 구조로 통일
- 기계용 code와 사람용 message 분리
- 스택 트레이스 등 민감 정보 배제
- 필드 단위 에러는 배열로 반환
¶ API 버전 관리
버전을 URL 경로에 둘지 헤더에 둘지는 오래된 논쟁이다.
| API 유형 | 권장 버전 관리 방식 |
|---|---|
| 불특정 외부 개발자용 공개 API | URL 경로 |
| 팀이 클라이언트를 통제하는 내부 API | 헤더 |
무엇이 "파괴적 변경"인지도 미리 합의해야 한다.
| 변경 유형 | 분류 |
|---|---|
| 필드 삭제 / 이름 변경 / 타입 변경 / 필수 파라미터 추가 | 새 버전이 필요한 변경 |
| 선택적 필드 추가 / 새 엔드포인트 추가 | 같은 버전에서 허용되는 변경 |
폐기 시에는 Deprecation·Sunset 헤더로 클라이언트가 마이그레이션 기한을 자동 감지하게 한다.
¶ 여러 팀이 API 표준을 함께 지키는 거버넌스
팀이 늘어나면 "원칙을 정하는 것"과 "원칙이 지켜지는 것"은 별개 문제가 된다. 처음 도입할 거버넌스는 무겁지 않아야 하며, 최소 구성은 다음 세 가지다.
- 네이밍·상태코드·에러·버전 규칙을 한 페이지로 정리한 스타일 가이드
- OpenAPI 스펙 변경분을 병합 전에 검토하는 리뷰 체크포인트
- 모든 소비 팀이 참조하는 단일 계약 문서
서비스가 3개 이상으로 늘어 인증·레이트리미팅을 중복 구현해야 할 때는 API 게이트웨이 도입을 검토한다. 조직 규모가 커지면 정기 감사로 표준 이탈("표준 부채")을 백로그로 관리하는 것도 고려할 수 있다.
¶ 참고할 만한 사례
| 구분 | 사례 |
|---|---|
| 국내 | 토스페이먼츠가 경로·요청·응답 일관성과 OAS 자동 생성으로 "설명 없이도 이해되는 API"를 지향한 사례 |
| 해외 | Stripe의 계정별 버전 고정 방식과 Google의 AIP(API Improvement Proposal) 공개 문서 체계 |
¶ 💬 질문이 있으신가요?
아래 댓글로 남겨주세요. 로그인 없이도 바로 남길 수 있습니다.