240709 REST API design guidelines

내맘대로 하지말자~ 컨벤션을 지키자.

새로 내가 거의 혼자(?) 개발을 진행하다보니 클라이언트측과의 소통이 많아지기 시작했다. 
정확히 필요한 것들을 말씀해주시는 클라이언트 개발자분을 만나서 많이 배우고 있다. 

필요한 소통을 위해 API 문서화를 위한 Swagger도 사용중이고, 클라 측에 딱 필요한 정보들만 담아 전달하기 위해 노력 중이다..! 

 

클라이언트 개발자 분께서 주신 메세지 중 내가 작성한 API에서 파라미터명이 여러가지가 혼용되고 있다는 이야기를 하셔서 다시 확인해보니, 카멜케이스/케밥케이스 왔다리 갔다리 하고있다.ㅠ ㅠ 

당연한 것이지만 무의식적으로  코드를 작성하다보면 마음대로 하게 된다. 이에 대한 의식적 배려와 노력이 필요함을... !!! 

 

그러는 김에 다시 한번 REST API design에 대한 가이드라인을 간단하게 정리해보았다.

 

1. Use HTTP protocols to define actions. url에는 행위를 정의하지 않고, HTTP 요청 메서드를 통해 행위를 정의한다. 

- POST (create)

- GET (retrieve information)

- PUT (update and replace information)

- PATCH (update and modify information)

- DELETE (delete)

 

2. Make all features CRUD compatible. CRUD 기능을 되도록이면 모두 만든다. 

 

3. Apply consistent formatting. 일관성 있는 포맷을 적용한다. 

- url에는 대문자 없이 소문자만 사용. & 케밥케이스 사용 

ex. GET /menu-orders

- 변수 PathVariable에는 카멜케이스 사용. 

- ex. GET /menu-orders/{menuOrderId}

 

- 일반적인 객체/ + 특정할 수 있는 identifier (seq, id 등) 이러한 방법으로 특정한다. 

ex. GET /tasks/123 > 123이라는 tasks를 조회

 

4. Make pagination programmable. 페이징처리를 해준다. limit & offset

- 개발자가 직접 파라미터로 페이징 크기를 조절할 수 있도록 한다. 

ex. GET /tasks?limit=10?offset=10 

 

5. 상태값 응답 방법

- Informational 1XX : 정보 제공

- Successful 2XX: 성공적인 응답-

- Redirection 3XX : 메시지 클라이언트의 요청을 완료하기 위해 추가적인 행동이 필요한 경우

- Client Error 4XX : 클라이언트가 서버에게 잘못된 요청을 하는 경우

• 401 unauthorized : 인증이 필요한 페이지를 요청한 경우
• 403 forbidden : 허용되지 않은 메서드가 있을 때 
• 406 not acceptable : 허용 불가능

- Client Error 5XX : 서버에서 오류가 발생하여 정상적으로 요청 처리 불가한 경우

• 500 Internal Server Error : 웹 서버가 처리할 수 없는 경우
• 503 Service Unavailable : 서비스 제공불가, 서버 과부하, 서버 폭주

 

6. 모니터링

- /health : 200 OK 의 상태값 반환 

- /version : API 버전 숫자를 응답

- /metrics : 평균 응답 시간과 같은 metrics를 응답.