출처: https://josipmisko.com/posts/rest-api-best-practices
개인 공부용으로 해당 포스트를 요약했습니다.
1) URI 네이밍 컨벤션 지켜라
2) 바른 HTTP methods를 사용해라
3) 적합한 데이터 구조를 사용해라
4) JSON 필드 네이밍 컨벤션 정하고 그걸 주구장창 써라
5) HTTP 상태 코드 잘 써라
6) 상태 유지 하지 마라
7) API 버전 관리해라
8) API가 변화한 내용을 온전히 문서화해라
9) 에러 메시지를 일관되게 사용해라
10) 하이퍼 미디어 링크를 제공해라
11) API 호출에 리밋을 두는 걸 고려해라
12) 쿼리 파라미터를 사용해라
URI 네이밍 컨벤션 지켜라
바른 HTTP methods를 사용해라
적합한 데이터 구조를 사용해라
JSON만 사용해야 한다는 건 경기도 오산이다.
리소스는 '뭐든' 상관 없다. 진짜다.
JSON 필드 네이밍 컨벤션 정하고 그걸 주구장창 써라
여기에 컨벤션, 스탠다드는 없다.
아무 거나 하나 집어서 주구장창 쓰면 그게 best practice다.
난 케밥 케이스 좋아한다.
(여기서는 케밥 케이스 추천 안 하네...)
HTTP 상태 코드 잘 써라
상태 유지 하지 마라
!REST API에서는 상태를 서버에 유지하면 안 된다.!
예를 들어, 쇼핑카트에서 상태 유지를 위해 쿠키를 사용할 수 있다.
근데 이거 RESTful APIs 원칙 위반이다.
RESTful API는 stateless해야 된다.
이게 뭔 소린가 하면...
RESTful API의 핵심 원칙 중 하나는 "상태를 유지하지 않아야 한다"입니다. 이것은 API 서버가 클라이언트의 상태를 저장하거나 관리해서는 안 된다는 것을 의미합니다. 그러나 장바구니와 같은 기능을 구현하는 데에는 다양한 방법이 있습니다.
클라이언트 측 상태 관리: RESTful API를 사용하는 클라이언트는 자체적으로 상태를 관리할 수 있습니다. 예를 들어, 클라이언트는 장바구니에 담은 상품 목록을 로컬 저장소 (로컬 스토리지 또는 쿠키)에 저장하고 필요할 때 이 정보를 API를 통해 전송합니다.
고유 식별자 사용: 장바구니와 같은 리소스를 관리할 때 고유 식별자를 사용합니다. 각 장바구니는 고유한 ID를 가지며, 이 ID를 클라이언트가 유지합니다. 클라이언트는 장바구니를 식별하기 위해 이 ID를 사용하고, 필요할 때 API에 전송하여 상태를 관리합니다.
세션 사용: 웹 애플리케이션에서는 세션을 사용하여 클라이언트의 상태를 일시적으로 관리할 수 있습니다. 그러나 이것은 RESTful API의 원칙과는 조금 다를 수 있습니다. 세션을 사용할 경우 상태를 서버 측에서 유지하게 됩니다. RESTful API에서 세션을 사용하는 것은 일반적으로 권장되지 않지만, 특정 상황에서는 필요할 수 있습니다.
유효 기간 설정: 클라이언트에게 특정 리소스 또는 상태의 유효 기간을 설정할 수 있습니다. 예를 들어, 장바구니에 담은 항목은 24시간 동안만 유효하도록 설정할 수 있습니다.
상태 유지를 피하면서도 장바구니와 같은 상태 관리가 필요한 경우, 위와 같은 방법을 고려할 수 있습니다. 이러한 방법은 RESTful API의 원칙을 준수하면서도 클라이언트의 요구사항을 충족시킬 수 있도록 도와줍니다.
원문이 조금 헷갈리게 표현하는 것 같은데
장바구니 등에서 쿠키 사용할 수 있다.
그런데 장바구니 상태를 서버에서 관리하면 안 된다.
장바구니 같은 거는 쿠키나 세션 통해서 관리한다.
API 버전 관리해라
API가 변화한 내용을 온전히 문서화해라
에러 메시지를 일관되게 사용해라
하이퍼 미디어 링크를 제공해라
API 호출에 리밋을 두는 걸 고려해라
429는 HTTP 상태 코드다.
Too Many Requests는 상태 메시지고
Retry-After는 헤더다.
쿼리 파라미터를 사용해라
생각해 볼 만한 사항
개발에 '답'은 없다는 걸 요즘 더더욱 느낀다.
