REST API 설계하는 법
안녕하세요. 남산돈가스입니다.
지난 포스팅 "REST란?"에 이어서 REST API를 설계하는 법에 대해서 포스팅하겠습니다.
RESTful한 API를 설계하기 위해서 가지고 있어야하는 세가지 특징을 Richardson Maturity Model(이하 RMM)을 가지고 설명드리겠습니다.
위 그림은 RMM 모델을 얘기하는데, Leonard Richardson가 정의한 REST 방식의 주요 요소들을 3개의 단계로 나눈 모델을 의미합니다. REST의 영광(?)을 얻기까지의 레벨을 총 0~3 단계로 표현했는데요.
각 단계 별로 설명드리겠습니다.
RMM Level 1 에서는 Resources(이하 리소스)를 도입합니다. URI 설계 시 리소스라는 개념을 도입하여 요청을 단일 서비스 endpoint로 보내는 것이 아니라, 각각의 리소스와 통신하게 됩니다.
예를 들어, 기존 /postService 로 모든 요청을 전달한 것에 비해서, 이제 /posts/1 과 같이 posts라는 리소스를 만들어 1번 게시글이라는 리소스를 이해할 수 있도록 URI를 설계하게 됩니다. 이렇게 다양한 URI를 사용하게 되었지만 아직 HTTP Method는 POST 하나만 사용하고 있는 상태입니다.
Level 2 에서 드디어 Level 1 의 URI Resources 와 HTTP Method 를 조합하여 사용함으로서 동일 리소스에 대해서 HTTP Method로 행위가 결정되었습니다. 추가적으로 HTTP Status Code 로 응답에 대한 결과 처리 또한 가능해졌습니다. 현재로서 가장 많은 RESTful API가 이 단계를 제공하고 있습니다.
GET /posts/1/comments?from=20200401&to=20200430 와 같이 리소스와 HTTP Method로 요청대상과 목적을 파악할 수 있게 되었습니다. 위 요청을 해석해본다면, posts(게시글) 중 1번의 게시글의 comments(댓글)을 GET(조회) 한다. 그 조건으로는 생성일 기준 from, to 기간 안에서 조회한다.
저 한 줄의 요청정보를 가지고 이제 우리는 어떤 리소스로 어떤 행위를 할 것 인지 서버로 요청할 수 있게 되었습니다.
추가적으로 HTTP Status Code를 언급했는데, 위 요청에 대해서 서버는 응답전문 이외로 Status Code로 클라이언트 간 커뮤니케이션이 가능해졌습니다.
마지막 Level 3 는 HATEOAS 라는 것의 도입입니다.
HATEOAS는 (Hypertext As The Engine Of Application State) 의 약어로, 한마디로 정리하면, 특정 API를 요청한 뒤 클라이언트 입장에서 이 응답을 받은 다음 단계로 할 수 있는 작업(전이) 을 알려주는 것이며, 다음 단계 작업을 위한 리소스의 URI를 서버에서 제공하는 것입니다. 이 단계를 적용하면 클라이언트는 다음 단계에 대한 행위를 클라이언트에서 관여하지 않고 서버에 응답으로서 행위를 정의할 수 있게 됩니다.
예를 들어, 위의 예시 처럼 1번 게시글에 작성 된 댓글들을 조회하는 API를 요청했다고 하면, 그 응답으로
조회한 결과(댓글 목록) 들을 볼 수 있는 화면의 링크나 그 댓글에 좋아요를 할 수 있는 API URI를 응답으로 제공하는 것입니다. 이렇게 응답에 리소스들로 할 수 있는 행위를 URI로 제공받는 다면 클라이언트는 그 응답만으로 다음 서버 처리가 가능하게 됩니다.
위에서 Level 0을 제외한 Level 1, 2, 3 에서의 특징인 Resources, Verbs(HTTP Method), HATEOAS를 가지고 API를 설계한다면 RESTful한 API를 설계할 수 있을 것입니다. 사실 말하자면, 저희가 개발하고 있는 API도 아직은 Level 2에 머무르고 있습니다. 하지만 RMM의 REST의 영광을 향해 개선을 거듭하려고 합니다. 이 포스팅을 통해서 RESTful을 바라보는 개발자분들 역시 REST의 영광을 얻기를 바라면서 포스팅 마치겠습니다.
감사합니다.
지난 포스팅 "REST란?"에 이어서 REST API를 설계하는 법에 대해서 포스팅하겠습니다.
RESTful한 API를 설계하기 위해서 가지고 있어야하는 세가지 특징을 Richardson Maturity Model(이하 RMM)을 가지고 설명드리겠습니다.
위 그림은 RMM 모델을 얘기하는데, Leonard Richardson가 정의한 REST 방식의 주요 요소들을 3개의 단계로 나눈 모델을 의미합니다. REST의 영광(?)을 얻기까지의 레벨을 총 0~3 단계로 표현했는데요.
각 단계 별로 설명드리겠습니다.
Level 0 : The Swamp of POX
웹의 기본 메커니즘을 전혀 사용하지 않은 단계로, HTTP Body로 데이터 통신을 하고 있긴하지만 POX(Plain Old XML)로 요청과 응답을 주고받는 RPC(Remote Procedure Call) 스타일의 시스템입니다. HTTP Method는 POST만을 사용하며, 서버로 요청하는 서비스는 그 자체로 하나의 endpoint를 가지게 됩니다.
쉽게 예를들자면, API 요청 도메인이 있고 게시판 기능을 하는 서비스를 만들었다고 한다면, POST /postService(게시판 서비스)와 같이 하나의 endpoint를 가지게 되고 이 endpoint로의 요청 Body의 addPost, getPost 등 필요로 하는 내용을 작성하여 요청을 전달하게 됩니다. 처음에 언급했듯이 HTTP가 제공하는 수많은 기능들을 모두 무시한 채 데이터를 통신하는 용도의 모델입니다.
쉽게 예를들자면, API 요청 도메인이 있고 게시판 기능을 하는 서비스를 만들었다고 한다면, POST /postService(게시판 서비스)와 같이 하나의 endpoint를 가지게 되고 이 endpoint로의 요청 Body의 addPost, getPost 등 필요로 하는 내용을 작성하여 요청을 전달하게 됩니다. 처음에 언급했듯이 HTTP가 제공하는 수많은 기능들을 모두 무시한 채 데이터를 통신하는 용도의 모델입니다.
Level 1 : Resources
예를 들어, 기존 /postService 로 모든 요청을 전달한 것에 비해서, 이제 /posts/1 과 같이 posts라는 리소스를 만들어 1번 게시글이라는 리소스를 이해할 수 있도록 URI를 설계하게 됩니다. 이렇게 다양한 URI를 사용하게 되었지만 아직 HTTP Method는 POST 하나만 사용하고 있는 상태입니다.
Level 2 : HTTP Verbs
Level 2 에서 드디어 Level 1 의 URI Resources 와 HTTP Method 를 조합하여 사용함으로서 동일 리소스에 대해서 HTTP Method로 행위가 결정되었습니다. 추가적으로 HTTP Status Code 로 응답에 대한 결과 처리 또한 가능해졌습니다. 현재로서 가장 많은 RESTful API가 이 단계를 제공하고 있습니다.
GET /posts/1/comments?from=20200401&to=20200430 와 같이 리소스와 HTTP Method로 요청대상과 목적을 파악할 수 있게 되었습니다. 위 요청을 해석해본다면, posts(게시글) 중 1번의 게시글의 comments(댓글)을 GET(조회) 한다. 그 조건으로는 생성일 기준 from, to 기간 안에서 조회한다.
저 한 줄의 요청정보를 가지고 이제 우리는 어떤 리소스로 어떤 행위를 할 것 인지 서버로 요청할 수 있게 되었습니다.
추가적으로 HTTP Status Code를 언급했는데, 위 요청에 대해서 서버는 응답전문 이외로 Status Code로 클라이언트 간 커뮤니케이션이 가능해졌습니다.
- HTTP Method의 종류 (대표적인 종류)
- GET : 정보를 요청하기 위해 사용
- POST : 정보를 입력하기 위해 사용
- PUT : 정보를 업데이트하기 위해 사용
- DELETE : 정보를 삭제하기 위해 사용
- OPTION, HEAD, PATCH 등등
- HTTP Status Code (대표적인 사용 코드)
- 200 : OK
- 201 : Created, 리소스가 정상적으로 생성
- 301 : Moved Permanently, 리소스의 URI가 변경 됨
- 400 : Invalid Request, 잘못 된 요청
- 401 : UnAuthorized, 인가되지 않은 요청
- 404 : Not Found, 리소스를 찾을 수 없음
- 500 : Internal Server Error, 서버의 내부 에러
Level 3 : Hypermedia Controls
HATEOAS는 (Hypertext As The Engine Of Application State) 의 약어로, 한마디로 정리하면, 특정 API를 요청한 뒤 클라이언트 입장에서 이 응답을 받은 다음 단계로 할 수 있는 작업(전이) 을 알려주는 것이며, 다음 단계 작업을 위한 리소스의 URI를 서버에서 제공하는 것입니다. 이 단계를 적용하면 클라이언트는 다음 단계에 대한 행위를 클라이언트에서 관여하지 않고 서버에 응답으로서 행위를 정의할 수 있게 됩니다.
예를 들어, 위의 예시 처럼 1번 게시글에 작성 된 댓글들을 조회하는 API를 요청했다고 하면, 그 응답으로
조회한 결과(댓글 목록) 들을 볼 수 있는 화면의 링크나 그 댓글에 좋아요를 할 수 있는 API URI를 응답으로 제공하는 것입니다. 이렇게 응답에 리소스들로 할 수 있는 행위를 URI로 제공받는 다면 클라이언트는 그 응답만으로 다음 서버 처리가 가능하게 됩니다.
위에서 Level 0을 제외한 Level 1, 2, 3 에서의 특징인 Resources, Verbs(HTTP Method), HATEOAS를 가지고 API를 설계한다면 RESTful한 API를 설계할 수 있을 것입니다. 사실 말하자면, 저희가 개발하고 있는 API도 아직은 Level 2에 머무르고 있습니다. 하지만 RMM의 REST의 영광을 향해 개선을 거듭하려고 합니다. 이 포스팅을 통해서 RESTful을 바라보는 개발자분들 역시 REST의 영광을 얻기를 바라면서 포스팅 마치겠습니다.
감사합니다.
댓글
댓글 쓰기