REST API 성숙도 모델

레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다.
이 모델의 2단계 까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우를 HTTP API 라고 부른다.

0단계

0단계에서는 리소스 구분 없이 단순히 HTTP 프로토콜을 사용하기만 한다.
하나의 엔드포인트만 사용해서 HTTP Method도 POST만 사용한다.
따라서 서로 다른 매개변수를 통해서 여러 동작을 하게 된다.
이 단계에서는 해당 API를 REST API라고 할 수 없으며, REST API를 작성하기 위한 기본 단계하고 볼 수 있다.

Request

POST /api/student
{
  "function": "getStudent",
  "arguments" [
    "1"
  ]
}

Response

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

CRUD

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

1단계

1단계에서는 리소스 개념을 도입한다. 모든 요청을 하나의 엔드포인트로 보내는 것이 아닌, 각기 다른 엔드포인트로 구분하여 개별 리소스와 통신한다.
또한, 요청에 따른 응답으로 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.

Request

POST /api/student/create
{
  "name': "sangbin"
}

Response

HTTP/1.1 200 OK
{
  "result" : "이미 있습니다."
}

CRUD

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

2단계

2단계에서는 CRUD에 맞게 적절한 HTTP Method를 사용하는 것에 중점을 둔다.
또한, Response에는 의미있는 HTTP Status Code가 반환된다.
성숙도 모델의 2단계까지 적용하면 대체적으로 잘 작성된 API라고 한다.

Request

PUT /api/student/create
{
  "name': "sangbin"
}

Response

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

CRUD

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

3단계

3단계의 요청은 2단계와 동일하지만, 응답에 리소스의 URI를 포함한 링크 요소를 삽입한다.
응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함한다.

Request

GET /api/student/1

Response

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