REST API (제약 조건)

REST API의 제약 조건

앞의 포스팅 처럼 REST API에는 총 6가지의 제약조건이 있다.

1. Server-Client 구조
2. Stateless(무상태)
3. Cacheable(캐시 처리 기능)
4. Layered System(계층화)
5. Code-On-Demand(Optional)
6. Uniform Interface(인터페이스의 일관성)

오늘날의 웹 브라우저에서는 HTTP의 프로토콜을 잘 지키므로 위와 같은 아키텍처 제약 조건을 잘 지킨다고 할수 있지만. Uniform Interface는 잘 지키지 못하는 경향이 있다.

Uniform Interface

Uniform Interface에도 4가지의 제약 조건이 있다.

1.Identification of resources
-> 리소스가 uri로 식별되면 된다.

2.Manipulation of resources through representations
-> Representation 전송을 통해서 리소스를 조작해야 한다. 즉 리소스를 CRUD 할 때 메소드를 저장하는 것을 말한다.

3.Self - Descriptive messages
-> 메시지는 스스로를 설명해야 한다.

4.Hypermedia as engine of application state(HATEOAS)
-> hypermedia로 애플리케이션 상태를 설명해야 한다.

오늘날의 REST API는 1,2번 만 만족하면 REST API라고 말하고 있지만, 사실은 4개의 조건을 모두 만족 시켜야 한다. http프로토콜을 사용 하므로 1,2은 모두 잘 만족하지만 3,4에는 부족한 경향이 있다. 오늘은 1,2,3 번에 대하여 이야기해 보겠다.

1.Identification of resources

• Resources가 uri로 식별되면 된다.

-> HTTP프로토콜을 따라서 각 리소스는 HTTP 전체에 사용되는 URI(Uniform Resources Identifier)에 의해서 식별 되고, 웹에서 리소스에 대한 식별과 위치는 대부분 단일 URL(Uniform Resource Locater)가 제공 된다.

-> 가끔 식별과 위치가 동일한 URI로 제공되지 않는데에 이유가 있는데, 이는 요청된 리소스에 대해 클라이언트가 다른 위치에서 접근하도록 해야 할 경우이다.

URI의 대표적인 두 종류, URLs, URNs

URLs
Uniform Resource Locater의 약자로, URL을 브라우저 주소 표시줄에 입력하면 연관된 리소스를 로드 할 수 있다.

ex)
http://jindream6128.tistory.com
http://jindream6128.tistory.com/en-US/docs/Learn/

URNs
Uniform Resource Name의 약자로, 영구적이며 소장 위치에 관계없이 정보 자원을 식별하는 고유 기호이다.

ex)
urn:urn:isbn:9780141036144 (George Orwell이 쓴 1984년이라는 책)
urn:ietf:rfc:7230 (IETF 스펙 문서 7230, Hypertext Transfer Protocol (HTTP/1.1)

2.Manipulation of resources through representations

• Representation 전송을 통해서 리소스를 조작해야 한다. 즉 리소스를 CRUD 할 때 메소드를 저장하는 것을 말한다.

-> 서버는 리소스 상태의 표현을 노출한다. 이는 기본적인 리소스의 데이터를 중립적인 형식으로 표시한다는 것을 의미한다. 웹 페이지의 데이터가 데이터베이스에 저장되는 방식과 유사하지만 보통 HTML형식으로 브라우저에게 전송 된다. 이것은 클라이언트가 리소스 서버 내부 구현에 대해 신경쓰지 않는다는 것을 의미한다.
서버는 리소스 데이터를 oracle DB, 플랫 파일에 저장하거나 프로시저 호출에 의해 생성될 수도 있다. 그것은 클라이언트에게 중요하지 않다. 클라이언트가 관심을 갖는 것은 서버에서 가져오는 Representations이다.

• 클라이언트가 api를 이용하여 메서드를 통해 서버를 호출한다. 서버는 호출을 받고 json, XML, HTML형식으로 클라이언트에게 Representations한다.

  REST API에서 정보를 호출하는 메서드 4개

3.Self - Descriptive messages

• 메시지는 스스로를 설명해야 한다.

HTTP 측면에서의 Self Descriptive

1. 응답 메시지의 Content - Type을 보고 text/html을 확인 가능.
2. HTTP 명세에서의 media type은 IANA에 등록되어 있다고 하므로, IANA에서 text/html 설명을 찾을 수 있다.
   IANA = Internet Assigned Numbers Authority 로서, 인터넷 할당 번호 관리기관의 약자로, IP주소나 최상위 도메인을 관리하는 단체.
3. IANA에 따라서 text/html의 명세가 링크임을 알수있고, 링크를 통해 명세를 해석할수 있다.
4. 명세에 모든 태그 해석 방법이 구체적으로 나와있으므로, 이를 해석하여 문자 저자가 사용자에게 구체적인 정보를 제공 할 수있다.

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이므로 링크를 통해 명세를 해석한다.

---

BUT Self Descriptive에 어긋나는 부분이 있다.
명세를 통해 Json문서를 파싱하는 방법은 명시되어 있다, 하지만 id값과 title값이 무었인지는 알수 없다.

Self-Descriptive를 지키는 방법 -1

• id값과 title값의 문제를 해결하기 위해 새로운 media type을 정의한다.
• 미디어 타입 문서에 id값과 title값을 정의한다.
• IANA에 미디어 타입을 등록하고 이때 만든 문서를 미디어 타입의 명세로 등록한다.
• 이제 명세를 찾아 이 메시지를 온전히 해석할수 있다.

BUT 매번 새로운 Media type을 등록해야하는 번거로움이 있다.

Self-Descriptive를 지키는 방법 -2

Profile

• Link 헤더에 profile relation을 통해 해당 명세 링크를 작성한다.
• 이제 메시지를 보는 사람은 명세를 찾아갈 수 있으므로, 온전히 해석이 가능하다.

BUT 클라이언트가 link헤더에 대하여 이해할수 있어야 하고, Content negotiation을 할 수 없다.

이렇게 self - descriptive를 만족 하여야 커뮤니케이션을 만들 수 있고, 서버나 클라이언트가 변경 되더라도 오가는 메시지를 통해 언제나 해석이 가능해 진다.

References

그런 REST API로 괜찮은가
mdn web docs
{REST:API}_links
생활코딩, Rest API