REST API

06 Oct 2022 •

Network

•

rest-api
network
roy-fielding
apache
rmm
richardson-maturity-model
glory-of-rest
the-swamp-of-pox
resources
http-verbs
hypermedia-control
http-methods
open-api
api-key

운세에 머리가 잘도는날이란다. 이런날 REST API를 배우게되다니 이건 행운이지 암.

다 읽고 작성하며 느낀거지만, API라는 개념부터 REST API가 단순히 잘만들어놓은 Library를 받아와 적절하게 땡겨쓰는 개념이 아니란걸 오늘 처음 알았다. 어쩐지 Google API나 Kakao API 구경만해도 어지러웠던 이유가 있었다.

정확한 개념을 모르니 그럴 수 밖에 T^T

Application Programming Interface(API), 대표적인 API Architecture로 개인 개발시에는 서버와의 통신 API를 어떻게 구현하는지는 중요하지 않지만, 협업에서는 다르다.

1. REST

Representational State Transfer(REST), Apache의 설립자 Roy Fielding의 논문에서 처음 소개된 개념으로 REST API는 “웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식”을 말한다.

2. RMM

Richardson Maturity Model(RMM), Roy Fielding이후 Leonard Richardson은 더 실용적으로 적용하기위한 성숙도 4단계 모델을 만들었다.

출처: codestates Rchardson 성숙도모델(RMM)

일반적으로는 3단계까지 지키기 어려워 2단계까지 적용한다. 그것을 HTTP API라 한다.

3. Glory of Rest

성숙도 4단계 사진 출처: 남산 아래 개발자들

3.1. Level 0: The Swamp of POX

출처: 남산 아래 개발자들

REST 성숙도 모델 0단계, Plain Old XML(POX), 0단계에서는 HTTP Protocol을 사용하기만 해도 된다. REST API를 작성하는 기본 단계이다.

// Requests
POST /alert HTTP/1.1
[header...]
{
  "uid": "0"
  "author": "ty",
  "time": "06:00",
  "per": "5",
  "content": "아침기상"
}

// Responses
HTTP/1.1 200 OK
[header...]

3.2. Level 1: Resources

출처: 남산 아래 개발자들

REST 성숙도 모델 1단계, Resources, 개별 리소스와의 통신을 준수해야한다. 모든 자원은 개별 리소스에 맞는 Endpoint를 사용해야한다. Request 후 받는 Resources에 대한 정보를 Responses로 전달하는 것이 핵심이다.

적절한 Endpoint사용이 중요한데, 동사, HTTP메서드, 어떤 행위에 대한 단어 사용은 지양하고, Resource에 집중해 명사 형태의 단어로 작성해야한다.

Requests에 대한 Responses로 Resources 넘겨줄 시 사용한 Resources 정보와 Success나 Fail 여부도 반환해야한다.

//예시를 보고 변경해본 예시가 Endpoint작성법에 위배되는지는 잘 모르겠다.

//Requests
POST /alert/detail/0 HTTP/1.1
[header...]

{
  "uid": "0"
  "author"
}

//Responses Success
HTTP/1.1 200 OK
[header...]

{
  "alert": {
    "detail": { "uid": "0", "author": "ty", ... },
    "uid": "0"
  }
}

//Responses Fail
HTTP/1.1 204 OK // <-- 요청에 대한 응답의 내용이 fail인거임!
[header...]

{
  "alert": {
    "detail": { "uid": "0", "author": "ty", ... },
    "uid": "0",
    "reason": "해당하는 아이템이 없습니다."
  }
}

3.3. Level 2: HTTP Verbs

출처: 남산 아래 개발자들

REST 성숙도 모델 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다. CRUD(CREATE, READ, UPDATE, DELETE)와 상관없이 POST메서드를 사용하고 있다.

GET메서드는 body가 없기때문에 query parameter를 사용하여 필요한 리소스를 전달한다.

// Requests READ
GET /alert/list?author=ty HTTP/1.1
[header...]

// Responses READ
HTTP/1.1 200 OK
[header...]

{
  "list": [
    { "uid": 0, "author": "ty", ... },
    { "uid": 11, "author": "ty", ... }
  ]
}

//Requests CREATE
POST /alert/insert/12 HTTP/1.1
[header...]

{
  "uid": "12",
  "author": "ty"
}

//Responses CREATE
HTTP/1.1 201 Created
Location: /alert/insert/12/detail
[header...]

{
  "detail": {
    "alert": { "uid": "12", "author": "ty", ... },
    "uid": "12"
  }
}

2단계 까지 충족해도 잘 설계된 API라고 한다. 3단계까지 만족하지 못할 시 REST API가 아닌, HTTP API라 부른다. -> 3단계까지 적용할 필요까지는 없다.(대부분이 2단계까지 적용한 HTTP API라 볼 수 있다.)

3.3.1. HTTP Methods 규칙

GET: 서버의 데이터를 변화시키지 않은 요청에 사용해야 한다.
POST: 요청마다 새로운 리소스를 생성한다. -> 멱등(imdempotent)하지 않다.
PUT: 요청마다 같은 리소스를 반환한다. -> 멱등(idempotent)하다고 한다.
PATCH: PUT이 교체라면 PATCH는 수정이다.

3.4. Level 3: Hypermedia Contorls

출처: 남산 아래 개발자들

Hypertext As The Engine Of Application State(HATEOAS), REST 성숙도 모델 3단계, 요청은 2단계와 동일하나, 응답에는 리소스의 URI를 포함한 “링크”를 삽입하여 작성한다.

응답에 들어가는 링크 요소는 응답을 받은 다음 할 수 있는 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함한다.

// Requests READ
GET /alert/list?author=ty HTTP/1.1
[header...]

// Responses READ
HTTP/1.1 200 OK
[header...]

{
  "list": [
    { "uid": 0, "author": "ty", ... },
    { "uid": 11, "author": "ty", ... }
  ],

  "links": {
    "alert": {
      "href": "https://127.0.0.1/alert/insert/13",
      "method": "POST"
    }
  }
}

/* 설계단에서 잘만 설계하면 서버측에서 넘겨주는 링크를 통해
프론트엔드단에서 강력하게 기능구현을 할 수 있을거같다. */

4. Open API

Open이란 말처럼 열려있는 API이다. 하지만 무제한으로 이용할 수는 없다. API마다 정해진 규칙이 있고, 제한사항(가격, 정보제한 등)이 있을 수 있다.

5. API Key

API 서버를 여는 Key이다. 필요없는 경우도 있지만, API key가 있어야 원하는 Responses를 받을 수 있다.

참조

APACHE:HTTP SERVER PROJECT
Wikipedia:Roy Fielding
남산 아래 개발자들:REST API 설계하는 법
MDN:HTTP/Methods
MDN:멱등(Idempotent)
공공데이터 포털
Open Weather Map:API
Google Cloud:API design
Microsoft:REST API Guidelines