REST API는 간단해 보이지만 잘 설계하기는 어렵다. 일관성 있고 직관적인 API를 만들기 위한 원칙과 실전 팁을 정리했다.
리소스 중심으로 설계하자. /getUsers 대신 /users를 쓴다. /createPost 대신 POST /posts를 쓴다. 동사는 HTTP 메서드가 담당한다. URL은 명사로만 구성한다.
HTTP 메서드의 올바른 사용
GET은 조회, POST는 생성, PUT/PATCH는 수정, DELETE는 삭제. 이것이 기본이다. GET은 멱등해야 한다. 같은 요청을 여러 번 보내도 결과가 같아야 한다. POST는 멱등하지 않다.
PUT과 PATCH는 다르다. PUT은 전체 교체, PATCH는 부분 수정이다. 이메일만 바꾸고 싶으면 PATCH를 쓴다. 전체 사용자 정보를 보내야 하면 PUT을 쓴다.
상태 코드
상태 코드를 정확하게 쓰자. 성공하면 200, 생성되면 201, 삭제 성공은 204. 클라이언트 잘못은 4xx, 서버 잘못은 5xx. 404는 찾을 수 없음, 403은 권한 없음, 401은 인증 필요.
200 OK를 남용하지 말자. 에러를 200으로 보내면서 body에 에러 메시지를 넣는 것은 안티패턴이다. 클라이언트가 응답 코드만 보고 성공 여부를 판단하게 하자.
버저닝과 페이지네이션
API 버전 관리가 필요하다. /v1/users, /v2/users 같은 URL 버저닝이 명확하다. 헤더 버저닝도 있지만 덜 직관적이다. 버전 업그레이드 시 호환성을 유지하자.
목록 API는 페이지네이션이 필수다. limit과 offset, 또는 cursor 기반으로 구현한다. 전체 개수와 다음 페이지 정보를 응답에 포함하자. 클라이언트가 페이지를 탐색할 수 있게 한다.
