TL;DR

• REST 아키텍처 스타일을 따르는 API.
• REST란 분산 하이퍼미디어 시스템을 위한 아키텍처 스타일로, 시스템이 상호운용성과 확장성을 지니게 하기 위한 조건을 제안한다.
• 통상적으로 REST API라고 부르는 것들은 REST를 온전히 지키지 않는 경우가 많은 것 같다. REST를 잘 지켰다는 것을 강조하고자 한다면 RESTful API로 부르는 것이 어떨까.

그런 REST API로 괜찮은가

웹 개발 동아리에 들어가서 스터디할 때, 1~2주차 스터디 커리큘럼에 포함된 내용이었다.
REST API에 대해 조사하면서 Naver D2 - 그런 REST API로 괜찮은가 강연 영상을 봤던 기억이 있다.
그때 당시에는 REST API는 고사하고 간단한 HTTP API도 만들어 본 적이 없었던지라, 수박 겉핥기 식으로만 보고 넘겼었다.

면접 스터디를 하면서 "REST API가 무엇인가요?" 라는 질문을 마주하였고, 이에 답하기 위해 22년 봄에 봤던 영상을 25년 봄에 다시 보면서 REST에 대한 개념과 나의 생각을 정리하고자 한다.

REST란?

REpresentational State Transfer의 약자. 분산 하이퍼미디어 시스템을 위한 아키텍처 스타일이다.

그렇다면 분산 하이퍼미디어 시스템이란?
하이퍼텍스트는 문서 내에서 링크를 통해 다른 문서로 이동할 수 있는 개념이다.
하이퍼미디어는 하이퍼텍스트에 이미지, 영상 등의 요소가 포함된 개념이다.
분산 시스템이란 여러 개의 독립된 컴퓨터가 네트워크를 통해 원격으로 연결된 시스템을 의미한다.
따라서, 분산 하이퍼미디어 시스템은 분산 시스템에서 하이퍼미디어를 공유하는 것으로, 웹이 대표적이다.

90년대 후반까지만 하더라도, 웹에 사용되던 API는 일관성이 떨어졌다. 제각기 다른 형식의 API를 사용했고, 서버가 달라지면 API도 달라져서 클라이언트 측에서 이를 해석하는데 힘이 들었다. API뿐만 아니라, 웹을 구성하는 다른 요소도 웹을 확장 가능하지 않게 만드는 방향으로 구현되고 있었다.

그래서 로이 필딩은 웹이 일관된 방식으로 사용될 수 있게, 확장 가능하게 하기 위해서 REST 스타일을 만들었다.

REST를 구성하는 스타일에는 다음과 같은 것이 있다.

• client-server
  • 클라이언트와 서버의 역할을 분리하고, 서로가 독립적으로 동작할 수 있게 설계되어야 한다.
• stateless
  • 서버는 클라이언트를 기억하지 않는다. 이전 요청과 상관없이 다음 요청을 처리해야 한다. 클라이언트가 서버에 종속되면 확장성에 불리해진다.
  • 서버가 이전 요청을 기억하지 않기 때문에 클라이언트는 매 요청마다 세션을 담아 보내야 한다.
• cache
• uniform interface
• layered system
  • 클라이언트와 서버 사이에 여러 계층(프록시, 로드밸런서, etc.)을 둘 수 있어야 한다. 클라이언트는 서버 사이에 무엇이 있는지 알 필요가 없게 한다.
• code-on-demand (optional)
  • 서버가 클라이언트로 코드를 전송하여 실행할 수 있는 개념. javascript 파일을 링크로 거는 일반적인 방식을 말하는 것이 아니고, HTTP 응답에 js 코드를 문자열로 보내는 느낌이다.

API를 설계할 때 특히 주목해야 할 요소가 바로 Uniform Interface이다.

Uniform Interface

4가지 요소가 존재한다.

• Identification of Resources
  • 모든 리소스가 고유한 URI를 가져야 한다.
• Manipulation of Resources through Representations
  • 리소스를 조작하는 행위가 표현되어야 한다.
  • 클라이언트가 서버로부터 받은 자원의 표현(JSON 등)을 수정해 다시 전송함으로써 자원의 상태를 간접적으로 변경하는 방식
  • 클라이언트가 서버의 내부 구조를 모르고도 자원을 조작할 수 있게 함
• Self-descriptive Messages
  • 요청과 응답이 자체적으로 필요한 정보를 포함해야 한다.
  • 응답이 어디서 왔는지(Host header), 내용을 어떤 방식으로 해석해야 하는지(Content-Type header) 등의 부가 정보를 포함해야 한다.
  • 클라이언트가 서버의 내부 구조를 모르고도 자원을 조작할 수 있게 함
• Hypermedia As The Engine Of Application State (HATEOAS)
  • 클라이언트가 서버의 상태를 예측하지 않고도, 응답을 보고 가능한 동작을 알 수 있어야 한다.
  • 서버가 응답할 때 현재 리소스와 관련된 추가 링크(Hypermedia)를 포함해야 하며, 클라이언트는 이를 보고 다음 동작을 알 수 있다.
  • 클라이언트가 서버의 내부 구조를 모르고도 자원을 조작할 수 있게 함

리소스라는 개념이 나와서 추가로 정리한다.
리소스란, 웹에서 다룰 수 있는 모든 데이터 대상, 식별하고자 하는 무언가를 의미한다. 게시판 서비스에서는 사용자, 게시글, 댓글 등에 해당될 수 있을 것이다. 이들 대상은 고유한 URI로 식별되어야 한다.

REST는 API를 위한 것인가?

아니다.
API는 분산 하이퍼미디어 시스템을 구성하는 하나의 요소이며, REST라는 거대한 스타일을 지키기 위해 고려해야 할 여러 요소 중 하나일 뿐이다.

REST API란?

REST API란, REST 아키텍처 스타일을 따르도록 설계된 API이다.
API가 REST 스타일을 따르게 하려면 적어도 Identification of Resources, Manipulation of Resources through Representations, Self-descriptive Messages, HATEOAS 는 만족 시켜야 할 것이다.

그러나, 실무적인 의미에서 REST API는 약간 다른 것 같다.
흔히 REST API를 구현한다고 하면, 다음과 같은 규칙을 따른다.

• URI는 동사보다는 명사로 작성한다.
• 단일 리소스는 단수 명사를, 여러 개의 리소스는 복수 명사를 사용하여 표현한다.
• 자원에 대한 행위는 HTTP 메서드(GET, PUT, POST, DELETE 등)로 표현한다.
• 소문자를 사용하고 합성어의 경우 hyphen(-)을 사용한다.

위와 같은 규칙은 Uniform Interface의 Identification of Resources, Manipulation of Resources through Representations을 지키게 도와주고, URI의 가독성을 올려주는 효과가 있다. 하지만, Self-descriptive나 HATEOAS는 고려하지 않는 규칙이므로 REST 스타일을 온전히 지킨 API라고는 말하기 힘들다.

그래서 RESTful이라는 용어가 나오지 않았을까 싶다. 원칙적인 개념과 실무에서 사용되는 개념이 달라서.
REST API를 실무적인 의미에서 통상적으로 지켜지는 관습이나 규칙을 따른 API로 본다면, 이는 REST 스타일을 완전히 지켰다고 보기 힘든 경우가 많으므로, RESTful API가 REST 스타일을 온전히 지킨 API를 의미하는 용어가 되게 한 것이 아닌가.