1. 정의
REST API란, representational state transfer 의 약자로, 웹에서 사용될 데이터나 자원의 요청경로를 URI 형태로 정의하고,
Http method( GET, POST, PATCH, DELETE... 등) 을 통해 어떤 형태로 작업하길 원하는지 설정하는 소통방식을 뜻한다.
좋은 REST API를 제작하기 위한 리차드슨이 제시한 피라미드 구조는 아래와 같다.
0단계 : http 프로토콜을 사용한다
가장 단순한 단계. 그냥 일반적인 request, response 형식의 소통을 진행한다.
1단계 : 개별리소스와의 통신 경로를 준수한다
REST API는 URI를 통해 데이터 자원의 경로를 표현해야 한다. 이 말인 즉슨, 필요한 데이터에 대해서 EndPoint는 적절하게 달라야 한다는 뜻이다.
위의 내용처럼, 특정 의사의 데이터를 요청하고 싶을 때 엔드포인트를 "/doctors/의사이름" 형태로 요청하는 것을 볼 수 있다.
그리고 특정 시간에 진료를 하고 싶을 때 요청의 엔드포인트를 "/slots/슬롯아이디" 형태로 요청을 하는 것을 볼 수 있다.
이처럼, 원하는 행위에 따라서 엔드 포인트는 달라져야 하고, 의미적으로 구분이 되어야 한다.
NOTE. 이때 엔드포인트는 관습적으로 절대 "Method type, 동사형태" 를 사용하지 않는다.
해당 행위의 자원 리소스에 맞춘 명사형태로 적어야 한다. (예를들어, 진료가능한 시간을 slot이라고 칭하고 엔드포인트를 설정하는 것이다)
2단계 : HTTP 메서드 규약을 준수한다
행위에 대한 의미론적인 메서드와 데이터 전달방식을 사용해야 하는 것을 뜻한다. 이것은 CRUD의 관점에서 이루어져야 한다.
예를 들어, 의사의 데이터를 가져오는 행위는 CRUD의 관점에서 보면 Read에 해당한다.
이때 어울리는 HTTP 메서드는 GET으로, body가 필요하지 않은 형태이다.
따라서, 요청을 위해 body로 데이터를 보내는 것이 아닌 URL에 query를 넣어 요청을 하는 것이 이에 해당한다.
NOTE. 만약 URL에 유저의 정보가 들어가는 것이 불안하다면, JWT를 이용하여 쿠키를 통해 사용자 인증을 하는 것을 권장한다.
요지는, GET을 위한 행위에 POST를 통한 요청을 하지 않는다는 점이다.
(물론, 이것은 구현하는 사람에 따라 다르다. 실제 NAVER API에서도 GET or POST를 통한 자원요청으로 문서화가 되어있는 부분을 일부 볼 수 있다.)
또한, Method들 역시 의미에 맞는 메서드를 써야 한다.
참고로 추가정리해야 할 부분을 나열하자면
POST : 서버의 데이터 자원을 추가하고, "항상 다른 결과" 를 리턴해야 한다.
PUT/PATCH : 서버의 데이터 자원을 변경하고, "항상 같은 결과를 리턴해야 한다. 또한, PUT은 데이터 전체가 변경될 때 PATCH는 데이터의 일부만 변경될 때 사용한다.
NOTE. 여기서 같은 결과, 다른 결과의 의미는 동일 엔드포인트에서는 동일한 응답이 온다는 뜻이다. 즉, POST는 매번 업데이트때마다 데이터베이스의 구조가 달라지기 때문에 응답이 어떤식으로든 다르게 오지만, GET의 경우, 동일 엔드포인트에서는 동일한 결과값이 리턴되므로 같은 결과를 가져온다는 것이다.
3단계 : 응답 데이터의 출처 소스를 나타낸다.
사실상 해당 내용까지 지켜지기는 어렵지만, 만약 필요로 한다면 응답 내용에 현재의 메서드가 어떤것이었고, 어떤 경로로 자원을 받아서 응답하는지에 대한 나열을 할 수 있다. (물론, 여기까지 지켜지기는 몹시 어렵기 떄문에 2단계만 되더라도 훌륭한 REST API라고 할 수 있다)
