모던 JS Deep dive #44 | REST API

2022년 12월 01일 15:38

REST

📌 REST의 배경

REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었다.

로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 한다.

REST 아키텍쳐를 웹 아키텍쳐중 하나인 HTTP 프로토콜과 동일 선상에서 해석하는 자료가 많지만 로이 필딩은 순수하게 REST 시스템을 구성하는 방법에 대해서만 소개했다.

웹과 무관한 REST 시스템을 본질을 먼저 이해하고, HTTP 프로토콜을 이용하여 REST 시스템을 설계하는 방법에 대해 이해하는 것을 목표로 하자.

📌 REST 구성

REST를 간단하게 말하자면, 존재하는 자원의 식별하고 제어하는 방법론 이다.

REST는 자원(URI), 제어(HTTP 요청 메서드), 표현(페이로드)으로 이루어져있다.

자원(Resource): 일이 처리되는 비용을 의미한다. REST는 소프트웨어 아키텍쳐 이므로 컴퓨터 자원을 의미하는 것이다. 컴퓨터 자원은 CPU가 수행하는 명령, 하드디스크에 저장되는 파일들, 메모리에 저장되는 데이터들을 의미한다.

REST의 식별자

REST는 컴퓨터 자원을 사용하여 처리하는 하나의 단위 작업을 식별할 수 있어야 하기 때문에 식별자가 필요하다.

예를들어 TIMESTAMP 나 UUID 같은 중복되지 않는 정보들을 식별자로 사용할 수 있다.
자원의 제어(Methods): CRUD 라 부르는 생성, 읽기, 변경, 삭제 행위를 자원에 수행하는 것을 의미한다. 이때 제어 방법은 일관적인 인터페이스로 구성되어야 한다(일관적이게 규칙을 따라야 한다).

예를들어 웹 기반(HTTP)의 시스템에서 자원의 변경을 POST 메소드로 한다면(PUT이 더 어울릴지라도) 자원의 변경은 POST 메소드로 일관적이게 처리해야 한다.
자원의 표현(Representations): 조회한 순간의 자원 상태를 의미한다.

REST의 자원의 표현은 자기 서술적인(self-descriptive, 데이터를 설명하는 메타 데이터) 메시지와 HATEOAS(hypermedia as the engine of application state, 다음 자원으로의 이동을 안내하는 하이퍼 텍스트 등이 포함 되는 데이터)로 구성된다.

REST 시스템은 클라이언트가 자원의 표현만 보더라도 이해되는 것을 목표로 한다.

📌 REST-FUL

우선 REST 시스템의 구성 요소는 다음과 같이 6개로 구성된다.

Client-Server
Stateless
Cacheable
Unitform-Interface
Layered-System
Code on demand (optional)

6가지 항목을 만족하는 HTTP REST 시스템을 구현한다고 가정할때, Unitform-Interface 항목을 제외한 나머지 항목들은 자연스럽게 구현이 되거나 조금만 신경을 쓴다면 어렵지 않게 구현할 수 있다.

Unitform-Interface 항목이 제외하는 이유는 Unitform-Interface를 제공하기 위해 수행해야할 특징 중 self-descriptive과 HATEOS는 HTTP 시스템에서 자연스럽게 처리 되지 않기 때문이다.

사실 self-descriptive과 HATEOS속성은 데이터가 독립적으로 자생하기 위해 필요한 요소들이라 볼 수 있다.

그렇다보니 HTTP서버 스펙을 구현할 때 데이터 독립적인 요소들까지 챙기지 않는 경우도 많습니다. 하지만 REST의 철학을 따르므로 REST시스템이라 부르고 있다.

REST의 구성요소를 완벽하게 지키지 않은 REST 시스템을 구분하기 위해서인지 REST의 구성요소 (특히 Unitform-Interface)를 완벽하게 지킨 REST시스템을 REST-FUL 시스템이라 부르고 있다.

로이 필딩은 REST 시스템의 규칙을 하나라도 제공하지 않는다면 REST 시스템이 아니라고 주장한다.

정리하자면 REST 시스템으로 소개 되고 있는 시스템은 Unitfor-Interface의 self-descriptive 와 HATEOS가 지켜지지 않는 경우도 많으며, 나머지 항목까지도 완벽히 구현한 시스템을 REST-FUL 하다고 표현 합니다.

REST API

📌 REST API란

말 그대로 REST를 기반으로 서비스 API를 구현한 것을 의미한다.

API는 컴퓨터의 자원 제어 방법의 집합이기 때문에, REST API는 REST 시스템의 자원 제어 방법의 집합으로 정의할 수 있다.

한단계 더 나아가 REST-FUL API는 REST의 구성요소를 완벽히 따른 시스템의 자원 제어 방법의 집합이라 정의할 수 있다.

🔥 REST API 설계 원칙

REST API 설계시 가장 중요한 기본적인 원칙은 2가지로 요약할 수 있다.

첫 번째, URI는 정보의 자원을 표현해야 한다.
```
GET /members/delete/1		(x)
```
URI는 자원을 표현하는데 중점을 두어야 한다. delete와 같은 행위에 대한 표현이 들어가서는 안된다.
```
DELETE /members/1				(o)
```

두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다. 회원정보를 가져올 때는 GET, 회원 추가 시의 행위를 표현하고자 할 때는 POST METHOD를 사용하여 표현한다.

GET /members/show/1     (x)
GET /members/1          (o)

GET /members/insert/2 (x)  - GET 메서드는 리소스 생성에 맞지 않습니다.
POST /members/2       (o)

METHOD	역할	페이로드
GET	모든/특정 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져옵니다.	X
POST	해당 URI를 요청하면 리소스를 생성합니다.	O
PUT	리소스를 전체 교체합니다.	O
PATCH	리소스의 일부를 수정합니다.	O
DELETE	모든/특정 리소스를 삭제합니다.	X

다음과 같은 방식으로 URI는 자원을 표현하는 데에 집중하고 행위에 대한 정의는 HTTP METHOD를 통해 하는 것이 REST한 API를 설계하는 중심 규칙이다.

참고자료

이웅모, 모던 자바스크립트 Deep Dive(위키북스, 2020), 제44장.

[네트워크] REST API