REST와 RESTful

세정·2024년 2월 5일

Representational State Transfer, 네트워크 아키텍처 원리 중 하나로, 분산 시스템을 위한 소프트웨어 아키텍처 스타일.

REST의 구성

자원 (Resource)

모든 것이 자원으로 표현된다. 각 자원은 고유한 식별자(URL)를 가지며, 이를 통해 자원을 식별한다.

URI (Uniform Resource Identifier)
특정 리소스를 식별하는 데 사용되는 일반적인 용어로, URL과 URN을 모두 포함한다. 예를 들어, http://www.example.com는 URI이다.

URL (Uniform Resource Locator)
URI의 하위 집합으로, 특정 리소스의 위치를 구체적으로 지정하는 특별한 유형의 URI이다. 예를 들어,http://www.example.com/resource는 URL이면서 URI이기도 하다.

행위 (Verb)

HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 자원에 대한 행위를 정의한다. 예를 들어, GET은 자원을 조회하고, POST는 자원을 생성하는 등의 행위를 정의한다.

표현 (Representation)

자원의 상태를 전송하는 방법으로, 주로 JSON, XML 등의 형태로 표현된다. 클라이언트와 서버 간에 자원의 표현을 전송함으로써 상호작용이 이루어진다.

자원과 URI

자원은 서버에 있는 개체나 데이터를 나타낸다. 예를 들어 사용자, 제품, 주문 등과 같은 개체일 수도 있고, 서비스에 대한 접근점을 가리킬 수도 있다. URI는 Uniform Resource Identifier의 약자로, 자원을 식별하기 위한 고유한 주소를 말한다. 클라이언트는 이를 사용하여 특정 자원에 접근하고 상호작용할 수 있다.

특정 쇼핑몰의 제품을 관리하는 RESTful 서비스가 있다고 가정해보겠다. 이 서비스의 자원은 각각의 제품을 나타내며, 각 제품은 고유한 식별자를 가지고 있다. 각 제품은 URI를 통해 식별된다.

https://example.com/products/ABC

이 URI를 통해 클라이언트는 서버에 제품 ABC에 대한 정보를 요청한다. 서버는 이 요청을 받아 해당하는 제품의 정보를 제공한다.

따라서, 자원은 서버에 있는 데이터나 개체를 가리키며, URI는 이러한 자원을 고유하게 식별하는 곳에 쓰인다.

HTTP 메서드

GET
자원을 가져올 때 사용된다. 서버에게 특정 자원을 요청하여, 데이터를 조회할 수 있다.
POST
새로운 데이터를 삽입할 때 사용된다. 일반적으로 HTML 폼 데이터나 JSON 데이터와 같은 형태로 새로운 데이터를 전송한다.
PUT
기존에 존재하던 자원을 전체 수정할 때 사용된다.
DELETE
기존에 존재하던 자원을 삭제할 때 사용된다.
PATCH
서버에 존재하던 자원의 일부를 수정할 때 사용된다.
HEAD
특정 자원에 대한 헤더 정보만을 가져올 때 사용된다. 실제 데이터는 요청하지 않고 헤더 정보만 확인할 수 있다.

설계 시 고려 요소

자원과 명명 규칙

자원은 고유한 식별자를 가져야 하며, URI는 자원을 식별하고 접근할 수 있도록 해야한다.
URI는 간결하고 직관적이어야 하며, 자원의 계층 구조를 잘 반영해야 한다.
자원 명명은 명확하고 일관되어야 한다. 예를 들어, /users는 모든 사용자를 나타내는 자원을 나타냄을 알 수 있다.

하테오스 (HATEOAS)

Hypermedia as the Engine of Application State, 하이퍼미디어를 애플리케이션 상태의 엔진으로 사용하는 개념.

Hypermedia
링크를 통해 서로 연결된 문서(자원)들 사이의 관계를 표현하는 개념.
ex) WWW 서비스

클라이언트는 서버로부터 받은 자원과 함께 해당 자원에서 가능한 동작에 대한 링크를 동적으로 받아와 클라이언트는 자원의 상태와 가능한 동작을 파악 및 수행할 수 있다.
클라이언트와 서버 간의 상호작용을 강화하고, 서비스의 유연성 및 확장성을 향상시킨다.
클라이언트는 Hypermedia 링크를 통해 서비스 내의 자원과 상호작용한다. 이는 클라이언트가 서비스의 상태를 이해하는데 도움이 된다.

RESTful API 설계 규칙

RESTful은 REST 원칙을 따르는 시스템이나 서비스를 말한다. RESTful한 시스템은 REST의 개념과 규칙을 지키면서 클라이언트와 서버 간의 상호작용을 가능케 한다. REST는 아키텍처와 스타일을 설명하는 개념이고, RESTful은 이러한 아키텍처 스타일을 따르는 시스템이나 서비스를 말한다.

명사형 자원과 적절한 HTTP 메서드 사용

API 엔드포인트는 각 자원을 나타내며, 명사로 구성된다. HTTP 메서드를 올바르게 사용하여 자원을 조작한다.

회원 관리 API 설계 예시 >
GET /users: 모든 회원 정보 조회
POST /users: 새로운 회원의 정보 생성
GET /users/{userId}: 특정 회원의 정보 조회
PUT /users/{userId}: 특정 회원의 정보를 변경
DELETE /users/{userId}: 특정 회원의 정보를 삭제

적절한 HTTP 상태 코드 사용

적절한 HTTP 상태 코드를 사용하여 요청의 결과를 나타낸다.

2xx: 클라이언트 요청이 성공적으로 처리.
- 200 OK: 요청이 성공적으로 처리되었고, 해당 리소스가 반환됨.
- 201 Created: 새로운 리소스가 성공적으로 생성됨.
- 204 No Content: 요청이 성공적으로 처리되었고, 응답 본문에 컨텐츠가 없음.
4xx: 클라이언트 측에서 잘못된 요청 혹은 부족한 권한으로 인해 발생한 오류.
- 400 Bad Request: 클라이언트의 잘못된 요청.
- 401 Unauthorized: 인증되지 않은 상태에서 보호된 리소스에 접근 시도. (인증 오류)
- 403 Forbidden: 클라이언트에게 권한이 없어 서버에 의해 거부됨. (권한 오류)
5xx: 클라이언트 요청을 처리하는 동한 발생한 오류.
- 500 Internal Server Error: 서버 처리 중 발생한 오류.
- 502 Bad Gatewqy: 게이트웨이 및 프록시 서버가 유효하지 않은 응답을 받았을 때 나타나는 오류.
- 503 Service Unavailable: 서버가 요청을 처리할 수 없을 때 나타나는 오류.

장단점

장점

간결성
HTTP 프로토콜을 기반으로 하며, 자원을 URI로 표현하고 HTTP 메서드를 사용하여 자원을 조작한다. 간단하고 직관적인 디자인으로, 시스템을 이해하고 사용하기 쉽다.
확장성
분산 시스템을 위한 훌륭한 아키텍처를 제공하여 확장성을 보장한다. 이는 시스템의 부하를 분산시키고, 새로운 요구사항에 유연하게 대응할 수 있다.
독립성
클라이언트와 서버 간의 독립성을 유지함으로써, 클라이언트와 서버를 독립적으로 업데이트 및 확장할 수 있다.
이해 용이성
자원 중심적 설계로, 자원에 대한 CRUD 작업이 명확하게 정의되어 이해하기 쉽다. 이는 시스템을 보다 쉽게 구축하고 유지보수 할 수 있게 된다.
상호 운용성
유니폼 인터페이스를 사용하면 서로 다른 시스템 간의 통신이 용이해진다. 유니폼 인터페이스는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다. 동일한 표준 인터페이스를 공유하므로 다른 플랫폼이나 언어를 사용해도 통신이 원활하다.

CRUD란?
기본적인 데이터 조작 기능을 나타내는 약어

Create: 생성(POST)
Read: 조회(GET)
Update: 수정(PUT, PATCH)
Delete: 삭제(DELETE)

단점

캐싱과 상태 관리
Stateless 프로토콜을 기반으로 하기에, 상태관리에 어려움이 있다. 클라이언트가 이전 상태를 알지 못하고, 서버도 클라이언트의 상태를 알지 못한다.
설계의 복잡함
RESTful 서비스를 설계할 때 적절한 자원 구조와 URI 설계, HTTP 메서드 사용 등을 고려해야 한다.