Network) Rest API란?

Rest API란?

Rest란 REpresentational State Transfer의 약자로 해석해보자면 Representation 상태를 전송한다는 것이다.
 
음.. 무슨 말인지 모르겠다.
 
찾아보니 Representation이란 어떤 리소스의 특정 시점의 상태를 반영하고 있는 정보이며, Representation Data와 Representation MetaData로 구성된다고 한다.

또한 REST는 위키 백과에 다음과 같이 나와있다.

REST는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍쳐의 한 형식이다.

 
이를 조금 더 풀어서 설명해보자.
 
REST API란 REST 아키텍쳐 스타일을 따르는 API이다. REST 아키텍쳐 스타일이란 분산 하이퍼미디어 시스템(대표적으로 WEB)을 위한 아키텍쳐 스타일이다. 아키텍쳐 스타일이란 제약조건들의 집합으로 이 조건들을 모두 지켜야 이 아키텍쳐 스타일을 만족한다고 할 수 있겠다.
 
즉, REST API란 REST 아키텍쳐 스타일에 정의된 제약 조건들을 따르는 API라고 할 수 있겠다. 그렇다면 REST는 어떤 제약 조건들이 있을까? REST 아키텍쳐는 다른 하위 아키텍쳐 스타일들의 집합이라고 볼 수 있다.
그 하위 아키텍쳐 스타일들은 다음과 같다.

REST 아키텍쳐 스타일

• client-server
• stateless
• cache
• uniform interface
• layered system
• code-on-demand(optional)
  • 서버에서 클라이언트로 코드를 보내서 실행할 수 있어야 한다. 즉, javascript를 서버로부터 다운받아 실행시킬 수 있어야 한다는 것이다.

다른 부분들은 HTTP 명세를 지키다 보면 자연스럽게 지켜지는 조건들이다. 하지만 이 중에서 매우 중요한 Uniform Inferface는 만족시키기 까다롭다. 그렇기에 여러분 중 대부분이 개발한 API는 RESTful API라고 부르긴 어려울 것이다.
 
Uniform Interface 아키텍쳐 스타일이 중요한 이유는 서버와 클라이언트가 독립적으로 진화하기 위해서이다. 애초에 REST가 등장한 것 자체가 로이 필딩이 HTTP를 수정했을 때 Web이 동작하지 않을 것을 걱정해서 등장한 것이기에 이러한 독립적인 진화가 중요할 수 밖에 없다.
 
그렇다면 Uniform Interface 아키텍쳐 스타일의 제약 조건은 무엇이 있을까?

Uniform Interface 아키텍쳐 스타일

• Identification Of Resources
  • 리소스가 URI로 식별되야 한다.
• Manipulation Of Resources Through Representations
  • Representation을 통해서 리소스를 조작해야한다. HTTP 메시지들을 통해 리소스를 조작하는 것이라고 보면 되겠다.
• Self-Descriptive Messages
  • 메시지들은 스스로 설명해야한다. 이는 각 메시지들이 메시지 내에 포함된 명세를 찾아가서, 메시지를 해석할 수 있도록 설명을 추가해야 한다는 것이다. ex) Content-Type: application/json-patch+json
• HATEOAS(Hypermedia As The Engine Of Application State)
  • 애플리케이션의 상태는 HyperLink를 통해 전달되어야 한다는 것이다.

이 중 특히 Self-Descriptive Message와 HATEOAS를 지키기 어려우니 신경써서 구현해보도록 하자.

Self-Descriptive Message와 HATEOAS를 JSON에서 지원하는 방법

Self-Description

1) Media Type

• 미디어 타입을 하나 정의한다.
• 미디어 타입 문서를 작성한다.
• IANA에 미디어 타입을 등록한다. 이때 만든 문서를 미디어 타입의 멍세로 등록한다.
• 이제 이 메시지를 보는 사람들은 명세를 찾아갈 수 있으므로 이 메시지의 의미를 온전히 해석할 수 있다.

단점 : 매번 media type을 정의해야한다.
2) Profile (Link 헤더)

• 의미를 정의한 명세를 작성한다.
• Link 헤더에 profile relation으로 해당 명세를 링크한다.
• 이제 이 메시지를 보는 사람이 명세를 찾아갈 수 있으므로 메시지의 의미를 온전히 해석할 수 있다.
• 단점 : 클라이언트가 Link 헤더와 profile을 이해해야 하며, Content negotiation을 할 수 없다.(미디어 타입으로 했을 때는, 클라이언트가 해당 타입에 대해 지원을 못하면 알아차릴 수 있는 Link 헤더로 하는 경우 이를 확인하지 못한다.)

HATEOAS

1) Data로

• data에 다양한 방법으로 하이퍼링크를 표현한다.
• 단점 : 링크를 표현하는 방법을 직접 정의해야한다.
• JSON으로 하이퍼링크를 표현하는 방법을 정의한 명세들을 활용한다.
• 단점 : 기존 API가 많이 수정되어야 한다.

2) HTTP 헤더로

• Link, Location 등의 헤더로 링크를 표현한다.
• 단점 : 정의된 Relation만 활용한다면 표현에 한계가 있다.

Spring에서 이를 구현하려면?

• Self Description : Spring Docs(Swagger)
• 툴을 이용해서 문서화를 시키고 이를 API에 명시해주는 방법이 있다.
• HATEOAS : org.springframework.boot:spring-boot-starter-hateoas
• 해당 프레임워크를 사용하여 HATEOAS를 구현할 수 있다.

참고

• 그런 REST API로 괜찮은가
• 잘 정리해놓으신 분
• Spring에서 HATEOAS와 Self Message
• REST란?
• Spring에서 HATEOAS 쓰는 법