본 글은 그런 REST API로 괜찮은가를 시청한 후 초심자의 눈높이에 맞게 작성한 글임을 밝힙니다.

API가 뭔가요?

Application Programming Interface(애플리케이션 프로그램 인터페이스)의 줄임말로, 두 프로그램(클라이언트-서버 등)이 소통하도록 제정한 규약입니다.

REST가 뭔가요?

Representational State Transfer 의 줄임말로, 웹을 위한 네트워크 기반 아키텍처 스타일입니다.

아키텍처 스타일이 뭔가요?

해당 스타일을 따르는 아키텍처가 지켜야 하는 제약조건들의 집합입니다.

그렇다면 REST의 제약조건들을 설명해주세요.

• Client-Server
  클라이언트-서버의 분리로 독립적인 개발을 이루며, 서로 영향을 끼치지 않는다.
  논문에서는 클라이언트-서버라고 작성되어있으나, 이는 브라우저-웹, 뷰-서버 등으로 볼 수 있습니다.
• Stateless
  클라이언트와 서버의 통신에는 상태가 없어야 하며, 모든 요청은 필요한 모든 정보를 담고 있어야 한다.
  상태를 서버에 두지 말고, 클라이언트에 의존하자는 항목입니다.
• Cache
  캐시가 가능해야 한다 - 모든 서버 응답은 캐시 가능한지 아닌지 알 수 있어야 한다.
  응답 메시지가 캐시 가능하다면, 클라이언트 캐시는 해당 메시지를 재사용할 권리가 생긴다고 보시면 되겠습니다.
• Uniform Interface
  구성요소 사이의 인터페이스는 일관성을 유지해야 한다.
  일관성을 지키는 방법은 이하 4가지 방법이 있습니다.
  - identification of resources
  리소스가 URI로 식별되도록 한다.
  특정 리소스를 식별할 때 /coupon/store 같은 형태로 접근 가능해야 함을 의미합니다.
  - manipulation of resources through representation
  리소스 표현은 메시지 형태로 전달, 메시지는 클라이언트와 서버간의 통신을 위한 표준 데이터 포맷을 사용해야 함
  리소스의 Representation이 JSON, XML 등의 포맷 형태로 전달되어야 함을 의미합니다. 리소스와 Representation의 차이는 REST의 representation이란 무엇인가를 참고하시면 되겠습니다.
  - self-descriptive messages
  메시지는 자체 서술적이어야 하며, 필요한 정보를 포함하고 있어야 함. 이를 통해 클라이언트는 메시지만으로 리소스와 상호 작용이 가능
  현재 HTTP API에서 지켜지지 않는 내용입니다. API를 설명하기 위한 문서가 본문 내에 포함되어야 한다는 뜻입니다. 이를 지키기 위해서는 IANA에 생성한 API 명세를 언제나 적어서 제출해야 합니다.
  - hypermedia as the engine of application state(HATEOAS)
  리소스의 표현은 리소스와 관련된 하이퍼링크를 포함해야 함. 클라이언트는 이를 통해 다음 가능한 상태와 작업을 이해하고 수행 가능
  현재 HTTP API에서 지켜지지 않는 내용입니다. 물론 하이퍼링크를 내부적으로 첨부하여 사용할 수 있으나, 모든 API에 연계되는 하이퍼링크를 작성하기 쉽지 않고, 이를 이용하며 View 페이지를 만드는 것 또한 현재의 View 구성 방향성과 벗어납니다.
• Layered System
  계층으로 구성이 가능해야 하며, 각 레이어에 속한 구성요소는 인접하지 않은 레이어의 구성요소를 볼 수 없어야 한다.
  사용자 인증, 암호화, 로드밸런싱 등의 계층으로 이루어질 수 있으며, 각각의 계층은 이전, 다음 계층과 데이터를 주고받을 뿐 다른 계층에게 영향을 끼쳐서는 안 됩니다.
• Code-On-Demand (Optional)
  서버가 네트워크를 통해 클라이언트에 프로그램을 전달하면 그 프로그램이 클라이언트에서 실행될 수 있어야 한다.
  JS등의 코드 전달을 통해 브라우저에서 특정 이벤트가 실행될 수 있도록 함을 뜻합니다. 필수는 아닙니다.

그래서 REST API는 무엇을 뜻하나요?

REST 논문을 작성한 로이 필딩의 말로는, 위의 모든 정의를 다 충족하는 API를 뜻한다고 합니다.
잘 지켜지고 있는 사항들을 제외하여 다시 설명한다면, 하이퍼텍스트를 포함한 self-descriptive한 메시지의 uniform interface를 통해 리소스에 접근하는 API라고 할 수 있겠네요.

그러나 지켜지지 않는 건, 이유가 있기 마련입니다. API는 REST 하기 어렵습니다.

왜 API는 REST 하기 어렵나요?

웹 페이지(브라우저 - 웹), HTTP API(뷰 - 서버)의 형태로 나눠 예시를 들어보겠습니다.

	웹 페이지	HTTP API
protocol	HTTP	HTTP
커뮤니케이션	사람-기계	기계-기계
Media Type	HTML	JSON

브라우저를 통해 웹을 보는 단계에서는, HTML을 통해 화면의 구성을 볼 수 있습니다.
그러나 웹 내에서의, HTTP API를 사용하는 단계에서는 주로 JSON을 통해 내부적인 메시지를 주고받으며 VIEW를 구성하게 됩니다.

	HTML	JSON
Hyperlink	가능(a 태그 등)	정의되어있지 않음
Self-descriptive	가능(HTML 명세)	불완전(문법만 정의)

HTML은 하이퍼링크 자체가 a태그로 약속이 되어 있으나, JSON은 따로 약속되어있지 않습니다.
또한 수많은 태그들은 HTML 명세를 보면 해석할 수 있으나, JSON은 문법 해석은 가능하지만 내부 필드들의 의미를 해석하려면 별도의 문서가 필요합니다.

해당 조건들에 맞춰서 API를 구성하면 되는 게 아닌가요?

네, 맞습니다. 그러나 쉽지 않을 겁니다.
API 구조 설계부터 각종 하이퍼링크 및 별도의 문서를 준비해야 하며, 해당하는 내용들을 모두 VIEW에서 의미있는 데이터로 만들어야 하기 때문입니다.

그렇다면, 현재 쓰이는 REST API는 어떠한 형태를 뜻하나요?

로이 필딩의 REST를 지키는 게 아닌, 권유 수준에서 작성된 API라 볼 수 있겠습니다.

실제로 로이 필딩은 아키텍처 스타일 중 하나라도 지키지 못 한다면 REST라고 부를 수 없고, 따라서 제발 REST API 말고 다른 용어를 써 달라고 합니다.

그러나 HTTP API들이 로이 필딩의 논문을 바탕으로 작성되어 왔고, 자체 서술 및 HATEOAS만을 미충족한 상태의 수많은 규약들로 작성된 API들이 REST API라고 불리우고 있습니다.

즉, REST 초기 설계에서 벗어났으나 Web의 발전에 맞게 재정의된 HTTP API가 현재의 REST API라고 일컬어진다 생각합니다.

예시로는 행위와 URL의 조합 및 각종 규칙 등이 있겠으나, [Network] REST란? REST API란? RESTful이란?의 글에서 잘 정리된 내용을 보실 수 있습니다.

참고한 글들
바쁜 개발자들을 위한 REST 논문 요약
논문을 통한 REST에 대한 고찰
REST API 뽀개기