스펙 PR
API 스펙 변경은 코드와 같은 방식으로 PR 리뷰를 거칩니다.
이 파트에서 다루는 내용
CH 05 혼자 쓰는 API 설계CH 06 팀으로 쓰는 API 설계CH 07 설계 시 자주 하는 실수
01
혼자 쓰는 API도 팀 기준으로 설계합니다
사이드 프로젝트라도 API 설계 습관은 그대로 굳어집니다. 처음부터 일관된 규칙을 세워두면 팀 프로젝트에 합류했을 때도 그대로 통합니다.
- 리소스 이름은 복수형 명사로 씁니다. 예: /product가 아니라 /products
- URL에 동사를 넣지 않습니다. 예: /getProducts 대신 GET /products
- 중첩 경로는 2단계 정도로 제한합니다. 너무 깊어지면 별도 엔드포인트를 검토합니다.
- 성공/실패 응답 포맷을 프로젝트 전체에서 통일합니다.
02
팀 API는 합의와 변경 관리가 핵심입니다
팀에서는 내가 아는 규칙이 아니라 팀이 합의한 규칙이 기준입니다. 프론트와 백엔드가 같은 스펙 문서를 보며 동시에 개발할 수 있어야 합니다.
API 변경은 코드 변경만큼 무겁게 다뤄야 합니다. 특히 기존 클라이언트를 깨뜨리는 Breaking Change는 리뷰, 공지, 버전 관리가 필요합니다.
고정 위치
Swagger UI URL, 스펙 파일 경로, 변경 이력 위치를 팀이 모두 알 수 있게 고정합니다.
Breaking Change
필드 삭제, 타입 변경, 상태 코드 의미 변경은 기존 클라이언트를 깨뜨릴 수 있어 버전과 공지가 필요합니다.
03
실무에서 자주 하는 실수를 먼저 피합니다
/getUserList
URL에 동작을 넣으면 REST 관점에서 자원 구조가 흐려집니다. GET /users로 표현합니다.
응답마다 다른 키
어떤 API는 result, 어떤 API는 data를 쓰면 클라이언트가 매번 다르게 처리해야 합니다.
모든 실패도 200
실패 여부를 본문까지 열어봐야 알게 됩니다. 인증, 권한, 요청 오류, 서버 오류를 상태 코드로 구분합니다.
페이지네이션 없는 목록
처음에는 빨라도 데이터가 늘면 응답이 무거워집니다. page/limit 또는 cursor 기준을 둡니다.
체크