REST API 설계 원칙
핵심
무상태(stateless)가 REST 의 핵심 제약입니다. 서버가 이전 요청을 기억하지 않으므로 요청 하나에 필요한 정보가 다 들어 있어야 하고, 그래서 서버를 늘리기 쉽습니다.
REST API 설계 원칙
핵심 원칙
- 리소스 중심 URL:
/users/123(O) vs/getUser?id=123(X) - HTTP 메서드 활용: GET=조회, POST=생성, PUT=수정, DELETE=삭제
- 적절한 상태 코드: 200, 201, 400, 401, 404, 500
URL 설계 규칙
| 좋은 예 | 나쁜 예 |
|---|---|
| GET /users | GET /getUsers |
| POST /users | POST /createUser |
| GET /users/123/orders | GET /getUserOrders?id=123 |
자원으로 안 떨어지는 것
대부분은 자원과 메서드로 표현됩니다. 그런데 안 떨어지는 것이 있습니다.
| 하려는 것 | 어떻게 두나 |
|---|---|
| 로그인 | 세션이라는 자원을 만든다고 본다 |
| 검색 | 조건을 질의 문자열로 받는 조회다 |
| 여러 건을 한 번에 처리 | 그 묶음을 자원으로 만든다 |
| 상태를 바꾸는 동작 | 상태를 자원의 한 필드로 본다 |
억지로 맞추지 않아도 됩니다. 대부분이 규칙을 따르고 몇 개가 예외인 것이, 규칙을 지키려고 이상한 주소를 만드는 것보다 낫습니다.
목록 응답에서 자주 빠지는 것
목록은 만들기 쉬워서 대충 넘어가기 쉽습니다.
상한이 없다: 클라이언트가 보낸 개수를 그대로 믿으면 한 번에 전부 가져간다
다음 페이지를 알 방법이 없다: 응답에 다음 위치를 담아야 한다
정렬이 정해져 있지 않다: 순서가 매번 달라 페이지가 어긋난다
셋째가 가장 늦게 발견됩니다. 정렬을 지정하지 않으면 저장소가 편한 순서로 주고, 그 순서는 데이터가 바뀌면 달라집니다.
실무 포인트
- 버전 관리:
/api/v1/users(URL 방식이 가장 보편적) - 페이지네이션:
?page=1&limit=20또는 커서 기반 - 에러 응답 표준화:
{ error: string, code: string }
면접에서 이렇게 나옵니다
- Q.좋은 REST API 설계 원칙은?
- Q.REST vs GraphQL 차이와 선택 기준은?
- Q.API 버저닝 전략을 설명해주세요