REST API - Maturity Model

Rechardson에 따르면 Rest api는 몇가지 레벨로 인해 구분된다.

사람에따라 Level 0 ~ 6 까지 나누는데 이 글에서는 Level 0 ~ 3 까지로 분류 한다.

 

 

 

 

Level 0 : URI, 1 HTTP method

 레벨 0은 하나의 endpoint를 통해 통신한다.

이는 매개변수를 통해 각 동작의 행위를 결정하기 때문에 HTTP method를 POST로 정의한다. 

 이를테면 아래와 같이 모든 CRUD 작업을 POST로 통일 한다는 의미이다.

 

CREATE : POST /user
READ : POST /user
UPDATE : POST /user
DELETE : POST /user

 

위와 같이 모든 작업을 POST와 같은 메소드로 매핑한다 그러나 각 작업에 대해 Body에 들어가는 값이 다르기 때문에 작업을 구분할 수 있다.

 

Level 1 : N URI, 2 HTTP method

Level 1 에서는 API 의 중요한 구성요소인 Resource의 개념이 도입된다. 

모든것이 POST로 가는것이 아닌 상황에 따라 개별 Resource로 통하나 모든 HTTP method로 통하지는 않는다.

즉 HTTP protocol을 제대로 활용하지는 못하는 단계라고 볼 수 있다. 

CREATE : POST /user/create
READ : GET /user/1
UPDATE : POST /user/update
DELETE : POST /user/remove/1

 

위와 같이 POST와 GET의 두가지 HTTP method 를 사용하고 있으나 뒤에 행할 작업에 대한 액션을 URI로 적용함으로서 불필요한 정보를 노출하고 있다. 실제로 처음 백엔드를 접하는 주니어의 사고방식으로 생각해 보았을때 이러한 방식이 좀 더 직관적이라고 볼 수 있으나 개발자의 의도가 URI부터 드러나는것은 옳지 않다.

또한 위 작업을 수행할 때 백엔드에서는 Status Code를 함께 전달한다. 

 

Level 2 : N URI, 4 HTTP mehthod

REST API를 처음 접할때 배웠던 것이 각 CRUD는 GET, POST, FATCH, PUT, DELETE 라는 HTTP method에 의해 좌지우지 된다는것이다. 이러한 작업이 제대로 확립되는 부분이 바로 이 Level 2 부분이다. 실제로 많은 서비스에서 이 Level 2까지 구현되어 있는 서버를 볼 수 있다. 이러한 작업이 가미될 때 클라이언트를 담당하는 개발자에게 훨씬 혼란스럽지 않은 개발환경을 제공할 수 있고 본인또한 보다 정형화된 문서를 구축할 수 있어 유리하다.

이 단계에서 요청에대한 성공은 200번대의 컨펌을 거친다. 실패는 4xx 번대 에러, 혹은 5xx번대 에러를 통해 잘못한 주체가 누구인지에 대해 알려주는것은 꼭 필요한 조치라고 생각한다.

 

CREATE : POST /user
READ : GET /user/1
UPDATE : PUT /user/1
DELETE : DELETE /user/1

Level 3 : 하이퍼 미디어를 통한 앱 상태

REST API의 진정한 단계가 바로 이 Level 3 단계라고 볼 수 있다. 이는 HATAEOAS 등을 사용해 REST API 호출시 URI에 하이퍼링크 형태로 다음 액션을 정의해 전달해주는 것이다. 이는 다음 동작에 대한 힌트를 주는것이라 할 수 있다. 요즘 API는 이러한 부가적인 요소들을 포함해 문서를 잘 작성해 제공하고 있다.