올바른 REST API 디자인 사례

1. 동사 대신 명사 사용하기

: 엔드포인트 경로 이름에는 개체를 식별할 수 있는 명사를 사용하기

/getAllClients > /clients

 

 

 

2. 복수형 명사 사용하기

: 리소스 명사에는 복수형을 사용하기

/employee/:id > /employees/:id

 

 

 

3. 일관성 유지하기

: 하나의 리소스에 대해 동일한 사례, 모든 엔드포인트에 대한 동일한 인증방법, 동일한 헤더, 동일한 상태 코드를 사용하기

 

 

 

4. 심플하게 유지하기

: 모든 엔드포인트의 이름을 리소스 지향적으로 설정하기

/users : 모든 유저
/users/124 :  특정 유저

 

 

 

5. 적절한 상태코드 만들기

: HTTP 상태 코드를 너무 많이 사용하지 말고 API 전체에서 동일한 결과에 동일한 상태코드 사용하기

 

 

 

6. 일반 텍스트(Plain text)를 반환하지 않기

: JSON 형식의 문자열로 본문을 반환하지 말고 Content-Type 헤더를 application/JSON으로 지정해서 응답해야한다

 

 

 

7. 적절한 오류 처리 수행하기

: 오류를 적절히 처리하고 무슨 일이 일어났는지 나타내는 응답코드(400~5xx)를 반환

: 상태코드와 함께 응답 본문에 일부 세부 정보를 반환해야함

 

 

 

8. 좋은 보안 관행을 갖추기

: 예외 없이 SSL/TLS를 사용하기

: 만료 날짜가 있는 사용자 정의 HTTP 헤더를 사용하여 전달되어야 하는 API 키 인증 수행

 

 

 

9. 페이지 매기기

: API가 많은 페이지를 반환하는 경우 page, page_size를 삽입할 것

/products?page=10&page_size=20

 

 

 

 

10. 버전 관리하기

: API 사용자가 다를 수 있으므로 첫 번째 버전부터 API 버전을 지정하기

/products/v1/4

 

 

 

 

Reference

서영 / 올바른 REST API 디자인 사례 : API 설계 가... | 커리어리

REST API Design Best Practices