RESTFul API 설계 팁

- Consumer first

개발하거나 설계하는 사람의 시각에서가 아닌 실제 사용하는 사용자 입장에서 직관적이고 명료하게 설계해야 한다. 소비자는 엔드 유저인 실제 고객이 아니라 이 api를 이용하는 사람이 될 것이다. 

 

- Make best use of HTTP

http의 메서드와 request, response 의 타입, 헤더값 등을 이용하는 등 http의 장점을 모두 사용해서 설계할 필요가 있다.

 

- Request methods

최소한 메서드의 4 종류는 구분하여 설계하라 . GET, POST, PUT, DELETE 를 이용하여 crud 를 구분하여 설계하자

 

- Response Status

각각의 api 요청에 따른 응답 코드가 전송되어야 한다 (200, 404, 400, 201, 401 등..)

이를 통해 성공했으면 왜 성공했는지 실패했으면 왜 실패했는지 등을 알 수 있다.

예를 들어 특정 메서드를 통해 회원 정보를 가져온다고 하면, 존재할 경우 200을 리턴하면된다. 그런데 만약 존재하지 않는다면 상태코드로 200을 리턴해야할지 아니면 404로 리턴해야할지를 정의해야한다. (보통 리소스가 없다면 404가 리턴된다는 인식이 있으니깐 ...)

 

- No secure info in URI

uri에는 비밀번호 같은 민감한 정보를 절대로 포함해서는 안된다. 스프링 시큐리티 등을 이용해서 토큰 방식으로 값을 전달해야한다

 

- Use plurals

복수형태로 쓰는 것이 일반적이다.

ex. /users -> o , /user -> x

      /users/1 -> o , /user/1 -> x

 

- User nouns for resources

모든 리소스는 가능하면 명사형태가 좋다. 명사형태가 더 간단명료하고 직관적이다.

 

- For exceptions

일관적인 엔드포인트를 사용하는 것이좋다. api gateway 등을 이용해서 각 서비스별로 동일한 엔드포인트 진입점을 만들어주자.