REST API란?

REST 정리 : REST란?

저번 글에서는 REST에 대해 정리를 해보았습니다 

그럼 REST API는 무엇일까요?

REST API는 REST 아키텍쳐 스타일을 따르는 API

하지만 오늘날 REST API라고 하는 API들의 대부분이 REST 아키텍쳐 스타일을 모두 따르지는 않습니다(2017년 기준)

그럼 REST API는 제약조건들을 다 지켜야하는 것이 아니라 몇개 빠뜨려도 되는 걸까요?

그에 대한 답은 모두 지켜한다고 Roy T.Fielding이 말을 했습니다

하이퍼텍스트를 포함한 self-descriptive한 메시지의 uniform interface를 통해 리소스에 접근하는 API

 -Roy T.Fielding

그렇다면 원격 API가 꼭 REST API여야 하는가?

시스템 전체를 통제할 수 있다고 생각하거나, 진화에 관심이 없다면, REST에 대해 따지느라 시간을 낭비하지마라

 -Roy T.Fielding

시스템을 통제할 수 있다는 뜻은 예를 들면 회사에서 내가 서버개발자인데 클라이언트 개발자를 통제할 수 있는 상황 또는 내가 클라이언트와 서버를 만들 때 라고 볼 수 있습니다. 진화에 관심이 없다는 뜻은 클라이언트와 서버가 독립전인 발전을 굳이 하지 않아도 된다는 뜻으로 생각할 수 있습니다. 모바일 어플리케이션처럼 무언가 바뀌었을 때 업데이트를 해도 괜찮다면 REST API를 꼭 지키지 않아도 됩니다. REST API를 지키기 위해서는 많은 노력과 시간이 들어가기 때문입니다.

그럼 REST API를 구현하려면 어떻게 해야할까?

웹 자체만 보았을 때는 REST가 잘 지켜졌는데 왜 REST API는 쉽지 않을까요?

일단 왜 API는 REST가 잘 안되는지 알아보도록 합시다

프로토콜은 HTTP로 동일하지만 HTTP API는 기계가 알아들을 수 있게 JSON 미디어 타입을 사용합니다

여기에서 문제가 발생합니다

JSON은 하이버링크가 정의되어 있지 않고, Self-descriptive의 경우 HTML은 HTML 명세에 HTML에 사용할 수 있는 모든 태그들이 정의되어 있지만 JSON은 오브젝트안에 키와 밸류가 어떤 의미를 가져야 하는지 정의되어 있지 않습니다. 불완전 하다는 의미는 문법적인 부분만 정의되어 있기 때문입니다.

문법은 해석이 가능하지만, 의미를 해석하려면 별도로 문서가(API 문서 등) 필요합니다

간단한 todo 리스트코드 라고 생각을 하고 비교를 한번 해봅시다

HTML의 Self-descriptive(코드만 보고 온전한 해석이 가능)

1. 응답 메시지의 Content-Type을 보고 media type이 text/html임을 확인한다

2. HTTP 명세에 media type은 IANA에 등록되어 있다고 하므로, IANA에서 text/html의 설명을 찾는다

3. IANA에 따르면 text/html 명세는 http://www.w3.org/TR/html 이므로 링크를 찾아가 명세를 해석한다

4. 명세에 모든 태그의 해석방법이 구체적으로 나와있으므로 이를 해석할 수 있다.

HTML의 HATEOAS

a 태그를 이용해 표현된 링크를 통해 다음 상태로 전이될 수 있으므로 HATEOAS를 만족한다

JSON의 Self-descriptive

1. 응답 메시지의 Content-Type을 보고 media type이 application/json임을 확인한다

2. HTTP 명세에 media type은 IANA에 등록되어 있다고 하므로, IANA에서 application/json의 설명을 찾는다

3. IANA에 따르면 application/json의 명세는 draft-ietf-jsonbis-rfc7159bis-04 이므로 링크를 찾아가 명세를 해석한다.

4. 명세에 json 문서를 파싱하는 방법이 명시되어 있으므로 성공적으로 파싱에 성공한다. 그러나 "id"가 무엇을 의미하고, "title"이 무엇을 의미하는지 알 방법이 없다

그러므로 온전한 해석을 할 수 없고, Self-descriptive하지 못하다

JSON의 HATEOAS

다음 상태로 전이할 링크가 없어 HATEOAS하지 못하다

그렇다면 Self-descriptive와 HATEOAS가 독립적 진화에 정말 도움이 될까요?

Self-descriptive

확장 가능한 커뮤니케이션이 가능하다

 - 서버나 클라이언트가 변경되더라도 오고가는 메시지는 언제나 self-descriptive하므로 언제나 해석이 가능하다

HATEOAS

애플리케이션 상태 전이의 late binding이 가능하다

 - 어디서 어디로 전이가 가능한지 미리 결정되지 않는다. 어떤 상태로 전이가 완료되고 나서야 그 다음 전이될 수 있는 상태가 결정된다.

 - 쉽게 말하면 링크는 동적으로 변경 될 수 있다. 서버에서 링크를 바꾼다고 해도 클라이언트의 동작은 문제가 없다. 바뀐 링크를 따라가면 되기 때문이다

 - 링크를 타고 전이가 된 다음에 그 페이지의 하이퍼링크들을 보고 나서 다음 전이될 링크를 확인 할 수 있어 late binding이 되기 때문에 서버가 링크를 동적으로 바꿀 수 있고 독립적인 진화가 가능하다

Self-descriptive와 HATEOAS가 독립적인 진화에 도움이 되므로 JSON을 REST API로 고쳐봅시다

Self-descriptive

방법 1 : Media type

1. 미디어 타입을 하나 정의한다

2. 미디어 타입 문서를 작성한다. 이 문서에 id가 무엇이고 title이 무엇인지 의미를 정의한다

3. IANA에 미디어 타입을 등록한다. 이 때 만든 문서를 미디어 타입의 명세로 등록한다.

4. 이제 이 메시지를 보는 사람은 명세를 찾아갈 수 있으므로 이 메시지의 의미를 온전히 해석할 수 있다.

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

방법 2 : Profile

Link에 rel에 "profile"을 하게 되면 JSON의 의미가 무엇인지 정보가 담긴 문서의 링크를 달 수 있게 된다

1. id가 무엇인지 title이 무엇인지 의미를 정의한 명세를 작성한다

2. Link 헤더에 profile relation으로 해당 명세를 링크한다

3. 이제 메시지를 보는 사람은 명세를 찾아갈 수 있으므로 이 문서의 의미를 온전히 해석할 수 있다.

단점 : 클라이언트가 Link 헤더와 profile을 이해해야한다.

   Content negotiation 할 수 없다. 미디어 타입이 아닌 Link헤더를 통해서 판단하기 때문이다.

*content negotiation MDN

HATEOAS

방법 1 : data로

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

단점 : 링크를 표현하는 방법을 profile이든 media type에 직접 정의해야 한다. 

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

- JSON API

- HAL

- UBER

- Siren

- Collection+json 등

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

방법 2 : HTTP 헤더로

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

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

HATEOAS의 경우 헤더와 data를 모두 활용하는 것이 좋다

몇가지 궁금증

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

Media type 등록은 필수 인가?

- 그렇지는 않습니다

저자의 의도를 사람들이 이해하면 안해도 된다. ( 예를 들면 회사 안에서 사용하는 API로서 사람들이 미디어 타입을 모두 이해하고 있다면 굳이 등록하지 않아도 된다 ) 하지만 하면 좋다

정리

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

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

- REST를 따를 것인지는 API를 설계하는 사람이 스스로 판단하여 결정해야 한다

- REST를 따르겠다면 Self-descriptive와 HATEOAS를 만족해야한다

- Self-descriptive는 custiom media type이나 profile link relation 등으로 만족 시킬 수 있다

- HATEOAS는 HTTP 헤더나 본문에 링크를 담아 만족 시킬 수 있다

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

- HTTP API라고 부를 수도 있고

- 그냥 지금처럼 REST API라고 부를 수도 있다