REST API (3)

왜 API는 REST가 잘 안되나?

일반적인 웹과 비교, 웹페이지 HTTP API

Protocol	HTTP	HTTP
커뮤니케이션	사람-기계	기계-기계
Media Type	HTML	JSON

 

REST API가 실패한 이유 : 커뮤니케이션, Media Type

 

 

HTML JSON 커뮤니케이션

Hyperlink	가능(a태그)	불가능
Self-descriptive	가능(html 명세)	불완전

 

Json이 불완전하다는 의미 : 대괄호, 중괄호 파싱, 배열 해석은 가능하지만 그 안에 있는 값이 무엇인지는 정의되지 않음.

따라서 JSON의 문법 해석은 가능하지만, 의미를 해석하려면 별도로 API 문서가 필요하다.

HTML은 REST를 성공하였다. 하지만 JSON은 REST를 성공하지 못하였다.

 

 

독립적인 진화에 도움

그런데 self-descriptive와 HATEOAS가 독립적인 진화에 어떻게 도움이 될까요?

 

- Self-descriptive

 

Self-descriptive는 확장 가능한 커뮤니케이션을 가능하게 한다. 서버나 클라이언트가 변경되더라도 오고 가는 메시지는 언제나 self-descriptive( 메세지만으로도 해석이 가능하다) 하므로 언제나 해석이 가능하다.

 

방법 1. Media type

1. 미디어 타입을 하나 정의한다
2. 미디어 타입 문서를 작성한다. 이 문선에 “id”가 뭐고 “title”이 뭔지 의미를 정의한다.
3. IANA에 미디어 타입을 등록한다. 이 때 만든 문서를 미디어 타입의 명세로 등록한다.
4. 이제 이 메시지를 보는 사람은 명세를 찾아갈 수 있으므로 이 메시지의 의미를 온전히 해석할 수 있다.

단점 : 매번 media type을 정의해야 한다.

 

방법 2. Profile

 

정보의 의미가 담긴 링크를 첨부할 수 있음 → 릴레이션을 프로필함

1. “id”가 뭐고 “title”이 뭔지 의미를 정의한 명세를 작성한다.
2. Link 헤더에 profile relation으로 해당 명세를 링크한다
3. 이제 메시지를 보는 사람은 명세를 찾아갈 수 있으므로 이 문서의 의미를 온전히 해석할 수 있다.

단점 : 클라이언트가 link 헤더(RFC 5988)와 profile 릴레이션(RFC 6906)을 이해해야 한다.

 

미디어 타입으로 했을 때는 클라이언트의 지원이 없을 때 서버가 알아챌 수 있지만, 프로파일은 오로지 링크로만 판단을 하여 Content negotiation을 할 수 없다.

 

- HATEOAS

 

HATEOAS 애플리케이션 상태 전이의 late binding이 가능. 어디서 어디로 전이가 가능한지 미리 결정되지 않는다. 어떤 상태로 전이가 완료되고 나서야 그 다음 전이될 수 있는 상태가 결정된다. 쉽게 말해서: 링크는 동적(마음대로)으로 변경할 수 있다. 서버가 링크를 바꿔도 클라이언트 동작에는 전혀 문제가 없다.

 

방법 1. data로

data에 다양한 방법으로 하이퍼링크를 표현한다.

JSON으로 하이퍼링크를 표현하는 방법을 정의한 명세들을 활용한다.

JSON API, HAL ,UBER ,Siren..

단점 : 기존 API를 많이 고쳐야한다. (침투적)

 

방법 2. HTTP 헤더로

Link, Location 등의 헤더로 링크를 표현한다.

단점 : 정의된 relation만 활용한다면 표현에 한계가 있다.

⇒ HATEOAS는 data와 헤더를 모두 활용하면 좋다.

 

Hyperlink는 반드시 uri여야 하는가?

uri - https://toss.im/users/eungjun

uri reference (absolute) - /users/eungjun

uri reference (relative) - eungjun

uri template - /users/{username}

 

Media type 등록은 필수인가?

• no
• 하지만 하면 좋다

Media type을 IANA에 등록하기

• 누구나 쉽게 사용할 수 있게 된다
• 이름 충돌을 피할 수 있다
• 등록이 별로 어렵지 않다(고 주장함)

 

 

최종정리

 

오늘날 대부분의 “REST API”는 사실 REST를 따르지 않고 있다.

REST의 제약조건 중에서 특히 Self-descriptive와 HATEOAS를 잘 만족하지 못한다.

REST는 긴 시간에 걸쳐 (수십년) 진화하는 웹 애플리케이션을 위한 것이다.

REST를 따를 것인지는 API를 설계하는 이들의 스스로 판단하여 결정해야한다.

REST를 따르겠다면, Self-descriptive와 HATEOAS를 만족시켜야한다.

• self-descriptive는 custom media type이나 profile link relation 등으로 만족시킬 수 있다.
• HATEOAS는 HTTP 헤더나 본문에 링크를 담아 만족시킬 수 있다.

REST를 따르지 않겠다면, “REST를 만족하지 않는 REST API”를 뭐라고 부를지 결정해야 한다.

• HTTP API라고 부를 수도 있고
• 그냥 이대로 REST API라고 부를 수도 있다. (roy 필딩이 싫어한다)