RESTAPI 에 대해 학습하기 앞써 ServerAPI 에 대한 개념부터 알아보았다.

API는 Application Programming Interface의 약자이며, Interface의 사전적 의미는 "의사소통이 가능"하도록 만들어진 "접점"을 의미합니다. 간단하게 이해하면 서버 API는 클라이언트가 서버에 적절한 요청을 하였을 때, 그에 맞는 응답을 되돌려주는 창구를 Web을 통해 노출한 것을 말합니다. 이를 이용해 우리는 서버로부터 정보를 요청하거나 수정할 수 있습니다. 이런 사용은 아무런 규칙 없이 이루어지는 것이 아닙니다. 요청과 응답을 할 때, '제대로 보내고 받을 수 있는' 일종의 규약이 존재합니다.

HTTP을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 메뉴판이 필요한데, 이 역할을 API가 수행해야 하므로 서로 잘 알아볼 수 있도록 작성하는 것이 중요합니다.

API 디자인은 보통 백엔드 개발자의 영역으로 알려져있습니다. 하지만 프론트엔드 개발자 또한 Mock API 디자인을 하거나 백엔드 개발자와의 원활한 협업을 해야하기 때문에 API 디자인 규칙 및 방법론을 알아야합니다. 서버 API 를 만드는 방법론 중에는 REST API와 GraphQL API가 있습니다.

REST API란 무엇인가?

REST API에서 REST는 “Representational State Transfer”의 약자로, 로이 필딩의 박사학위 논문에서 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로써 처음 소개되었습니다. REST API는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말합니다. 이 방법론은 많은 Server API 들을 구성하기 위해 사용되었고, 또 현재도 많이 사용되고 있습니다.

REST API에서는 HTTP 메서드를 이용해 서버와 통신합니다. GET을 통해 웹 페이지나 데이터를 요청하고, POST로 새로운 글이나 데이터를 전송하거나 DELETE로 저장된 글이나 데이터를 삭제할 수 있습니다. 이처럼 클라이언트와 서버가 HTTP 통신을 할 때는 어떤 요청을 보내고 받느냐에 따라 메서드의 사용이 달라집니다.

로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했습니다. 그러나 실제로 엄밀하게 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우 HTTP API 라고도 부릅니다.

아래는 성숙도 레벨별 샘플 코드이다.

Level 1 : N URI, 2 HTTP method

Request

POST https://api/userService
{
  "function": "getUserInfo",
  "arguments" [
    "1"
  ]
}

Response

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

CRUD

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

Level 2 : N URI, 4 HTTP method

Request

PUT https://api/users
{
  "name" [
    "explorer_cat"
  ]
}

Response

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

CRUD

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

Level 3 : Hypermedia As Engine of Application State

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" {
    "name": "Ohjongsung",
    "id": "1",
    "nextActions": {
       "/api/users/{userId}/roles",
     }
  }
}

Level 4 : API Versionning

Request

GET https://api/v1/users/1

Request

GET https://api/users/1
Accept: application/vnd.app-1.0+json

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result" {
    "name": "Ohjongsung",
    "id": "1"
  }
}

Reference

https://damienfremont.com/2017/11/23/rest-api-maturity-levels-from-0-to-5/
http://jinson.tistory.com/190
https://blog.goodapi.co/api-maturity-fb25560151a3
https://blog.naver.com/saltynut/220758336130