REST API 성숙도 모델 (Maturity Model)

2020년 12월 14일 기록
이번에는 REST API 성숙도 모델에 대해 정리해볼 것이다. 성숙도 모델은 총 4단계로 나누어져서 각 단계를 달성할 수록 REST API에 가까워진다. 정확히 이해가 되진 않았지만, 여기저기 참고해서 이해한 만큼 정리해보려고 한다. 참고 : Rechardson의 API 성숙도 모델

Level 0 : 1 URI, 1 HTTP method

level 0은 웹 메커니즘을 사용하지 않고 HTTP를 원격 통신을 위한 전송 시스템으로 사용한다. RPC(Remote Precedure Call) 형태로 리소스 구분 없이 설계된 HTTP API이다.

그저 단순하게 POX(Plain Old XML)를 주고 받는 RPC 스타일 시스템을 말한다. 단 하나의 endpoint를 사용하고, 전달되는 서로 다른 매개변수를 통해 하나의 endpoint에서 여러 동작을 하게 된다. 매개 변수를 body로 전달하기 위해 HTTP method는 POST가 된다.

Request

POST https://api/user
{
  "function": "getUser",
  "arguments" [
    "1"
  ]
}

Response

HTTP/1.1 200 OK
{
  "result" {
  	"id": "1"
    "name": "yoonyoung",
  }
}

CRUD

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

Level 1 : N URI, 2 HTTP method

리소스를 도입한다. 모든 요청을 단일 서비스 endpoint로 보내는 것이 아니라 개별 리소스와 통신하게 된다. 리소스별로 고유한 URI를 사용해서 식별한다.

Request

POST https://api/users/create
{
  "name": "yoonyoung"
}

Response

HTTP/1.1 200 OK
{
  "result" {
    "error": "already exist member"
  }
}

CRUD

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

HTTP method는 GET과 POST만 사용하고 있고, Response에서는 error인 경우에도 Status Code를 200으로 전달하고 있다. 또 HTTP headers에 Content-Type이나 Cache 관련 정보를 제공하지 않는다.

Level 2 : N URI, 4 HTTP method

2단계에서는 HTTP method인 GET, POST, PUT, DELETE를 사용해 CRUD를 나타내고 메시지에 Status Code도 담겨 반환한다. GET은 상태를 변화시키지 않는 안전한 Action을 나타내고, 안전하게 얼마든지 호출할 수 있고 매번 같은 결과를 얻도록 한다. 그리고 캐싱을 할 수 있어 사용자 입장에서 성능 향상도 느낄 수 있다.

설명에서는 GET, POST, PUT, DELETE의 4가지 CRUD를 사용한다고 나와있지만, POST와 GET만 사용해도 충족되는 것 같다.

Request

PUT https://api/users
{
  "name": "yoonyoung"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json
{
  "result" {
    "id": "1",
    "name": "yoonyoung"
  }
}

CRUD

CREATE : POST /api/users
READ :   GET /api/users/1
UPDATE : PUT /api/users/1
DELETE : DELETE /api/users/1

2단계에서는 URI에 action이 담기지 않고, 멱등성을 보장하는 GET에는 캐시가 적용된다. Response에는 의미있는 HTTP Status Code가 반환된다. Status Code를 모두 활용할 필요는 없고, 클라이언트 입장에서 200 OK인지, 클라이언트 잘못(400 Bad Request) 인지, 서버 잘못(500 Internal Server Error)인지 정도를 알 수 있도록 전달해주면 충분하다. 다만, 실패일 경우 Body에 왜 실패했는지 정보를 보내주면 좋다.

Level 3 : Hypermedia As Engine of Application State

3단계까지는 와야 진정한 REST API라고 한다. API 서비스의 모든 endpoint를 최초 진입점이 되는 URI를 통해 Hypertext Link 형태로 제공한다. 요즘 API는 API 문서를 제공하지만 단순한 API 목록 제공뿐만 아니라 어떤 request의 다음 request에 필요한 endpoint까지 제공한다. 클라이언트에게 다음에 어떤 동작이 가능한지 힌트를 제공할 수 있다.

다음에 무엇을 할 수 있는지, 그것을 하기 위해 다루어야 할 리소스의 URI를 알려줄 수 있다. 서버가 클라이언트에 문제를 일으키지 않고 URI scheme을 변경할 수 있다. 클라이언트가 링크 URI를 찾는 동안, 서버 팀은 최초 진입점을 제외한 모든 URI 작업을 할 수 있다.

Request

GET https://api/

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "/api/users",
  "/api/users/{userId}/roles",
  "/api/products",
  "/api/..."
}

Request

GET https://api/users/1

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
 "result" {
    "id": "1",
    "name": "yoonyoung",
    "nextActions": {
       "/api/users/{userId}/roles",
     }
  }
}