REST, REST API, RESTful

wujin·2023년 6월 8일

REST (Representational State Transfer)

REST(Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미한다.

즉 REST란

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
HTTP Method(POST, GET, PUT, DELETE, PATCH 등)를 통해
해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미한다.

REST 구성 요소

자원(Resource) : URI
- 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
- 자원을 구별하는 ID는 ‘/groups/:group_id’와 같은 HTTP URI 이다.
- Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다.
행위(Verb) : HTTP Method
- 자원에 대한 행위는 HTTP 프로토콜의 Method를 통해 표현된다.
- HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공한다.
표현(Representations) : HTTP Message Pay Load
- Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
- REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
- JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다.

REST의 특징

Client-Server(서버-클라이언트 구조)
REST는 클라이언트와 서버 간의 역할을 분리한다.
이렇게 함으로써 클라이언트와 서버는 각각 개발될 수 있고, 이는 각자의 분야에서 독립적으로 발전하고 확장될 수 있다는 이점을 제공한다.
Stateless(무상태)
REST는 상태가 없는(stateless) 프로토콜이다.
각 요청 간에 클라이언트의 컨텍스트가 서버에 저장되지 않음을 의미한다.
각 요청은 서버가 이전에 만든 요청에 대한 정보 없이 처리되어야 한다.
이로 인해 서버의 확장성이 향상된다.
Cacheable(캐시 처리 가능)
REST의 표준 HTTP 프로토콜을 기반으로 한 캐싱 기능은 클라이언트가 서버의 응답을 캐시하고 재사용할 수 있게 한다.
이를 통해 클라이언트의 성능과 효율성이 향상될 수 있다.
Layered System(계층화)
클라이언트는 바로 연결된 서버에만 응답을 보낼 수 있으며, 중간 서버는 요청이나 응답을 전달하는 역할을 한다.
이는 네트워크 기반의 인프라를 사용하여 서버나 클라이언트를 쉽게 변경하고 업데이트할 수 있게 한다.
Uniform Interface(인터페이스 일관성)
REST는 일관된 인터페이스를 제공한다.
이는 자원 지향 아키텍처, HTTP 메소드(GET, POST, PUT, DELETE 등), 자원에 대한 식별을 위한 URI, 그리고 메시지 포맷(JSON, XML 등)을 포함한다.
Code on Demand (optional)
필요한 경우, 서버는 실행 가능한 코드를 클라이언트에게 제공하여 클라이언트의 기능을 확장할 수 있다.
이는 선택적인 요구사항이며, 일반적으로는 사용되지 않는다.

이러한 특징들 덕분에 REST는 확장성이 뛰어나며 유지보수가 쉽고, 다양한 유형의 클라이언트와 상호작용할 수 있습니다.

REST의 장단점

장점

별도의 인프라 구축 필요 없음
REST API는 HTTP 프로토콜의 인프라를 그대로 활용한다.
따라서 별도의 인프라를 구축할 필요가 없으며, 이는 비용 및 시간을 절약하는 데 도움이 된다.
명확한 메시지
REST API 메시지는 의도하는 바를 명확하게 나타낸다.
이를 통해 개발자는 API의 동작을 쉽게 이해하고 예측할 수 있다.
표준화된 인터페이스
REST는 HTTP 메소드와 URI를 이용하여 자원에 접근한다.
이는 개발자가 API를 이해하고 사용하는데 있어 일관성을 제공하며, 학습 곡선을 낮춘다.
Scalability (확장성)
REST의 Stateless 특성은 서버 측에서 클라이언트 정보를 저장하지 않으므로, 서버의 확장성을 향상시키는 데 도움이 된다.
Performance (성능)
REST는 캐싱 기능을 지원합니다. 이는 반복된 요청에 대한 응답 시간을 줄이고 서버 부하를 줄여 성능을 향상시킵니다.
Separation of Concerns (관심사의 분리)
REST는 클라이언트와 서버 간의 역할을 명확히 분리합니다. 이는 개발 프로세스를 단순화하고, 각 구성 요소를 독립적으로 확장하거나 수정하는 데 유리합니다.

단점

Limited Methods (제한된 메소드)
REST는 HTTP 프로토콜에 의존하며, HTTP 메소드의 제한된 세트 (GET, POST, PUT, DELETE 등)를 사용하여 모든 종류의 트랜잭션을 표현해야 한다.
이는 때때로 충분한 표현력을 제공하지 못할 수 있다.
Overhead
REST는 메타데이터, 헤더 정보, URI 등을 통해 데이터를 전송한다.
이는 비효율적인 데이터 전송을 초래하며, 특히 모바일 네트워크와 같이 대역폭이 제한된 환경에서는 부담이 될 수 있다.
Stateless Limitations (상태 없음의 한계)
REST의 Stateless 특성은 각 요청이 독립적으로 처리되어야 함을 의미한다.
이는 서버가 클라이언트의 상태를 추적하지 않음을 의미하며, 이로 인해 일부 연산에서는 비효율적일 수 있다.
Difficulty in Managing Real-Time Communication
REST는 실시간 통신이나 소켓 통신 같은 상황에는 적합하지 않다.
이런 경우에는 WebSocket이나 GraphQL 등의 기술이 더 적합하다고 볼 수 있다.
브라우저 호환성 문제
구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(ex. 익스폴로어)

REST API

REST API는 REST 원칙을 따르는 애플리케이션 프로그래밍 인터페이스이다.
클라이언트가 서버의 자원에 접근하고 조작하는데 사용된다.

설계 주요 규칙

자원(Resource)은 URI(Uniform Resource Identifier)로 표현 / URI는 동사보다는 명사를, 대문자보다는 소문자를 사용
웹 서비스의 각 자원은 고유한 URI에 의해 식별되어야 한다.
URI는 해당 자원을 명확하게 표현하며, 자원 간의 관계를 나타낼 수 있다.
URI는 자원을 표현하는 명사 구조를 사용하며, 해당 자원에 대한 조작은 HTTP 메소드를 통해 나타낸다.
대/소문자에 관해서는 일관성을 유지하기 위해 소문자를 주로 사용한다.

Bad Example
/Running
Good Example
/run
/users
/users/1

마지막에 슬래시 /를 사용하지 않는다.
URI의 마지막에는 슬래시(/)를 붙이지 않는다.
이는 URI의 일관성을 유지하는데 도움이 된다.

Bad Example
/users/
Good Example
/users

언더바 대신 하이픈을 사용
URI에서는 가독성을 높이기 위해 단어 사이를 구분하는 데 언더바(_) 대신 하이픈(-)을 사용하는 것이 일반적이다.

Bad Example
/user_profile
Good Example
/user-profile

파일 확장자는 URI에 포함하지 않는다.
자원의 표현 형식을 결정하는데 파일 확장자 대신 Accept 헤더를 사용한다.
따라서 URI에 파일 확장자를 포함시키지 않는다.

Bad Example
/users.json
Good Example
/users (클라이언트가 JSON 형식을 원하는 경우, Accept: application/json 헤더를 사용)

표현(Representation)에 대한 통신
클라이언트와 서버 간에 전송되는 데이터는 해당 자원의 '표현'이다. 이 표현은 주로 JSON이나 XML 형태로 전달된다.
아래는 POST 요청으로 새 사용자를 생성하는 경우, 요청 본문에는 해당 사용자의 표현이 포함된다.

POST /users
Content-Type: application/json
{
    "name": "John Doe",
    "email": "john.doe@example.com"
}

행위를 포함하지 않는다. / HTTP 메소드를 이용한 자원의 조작
자원의 표현 행위는 URI에 포함하지 않는다.
HTTP 메소드를 사용하여 자원을 생성, 조회, 업데이트, 삭제하는 CRUD 연산을 표현한다.

Bad Example
/users/1/select
/users/1/update
/users/1/delete
Good Example
GET /users (모든 사용자를 조회)
POST /users (새 사용자를 생성)
PUT /users/1 (id가 1인 사용자를 업데이트)
DELETE /users/1 (id가 1인 사용자를 삭제)

상태 코드(Status Code) 사용
HTTP 상태 코드는 서버 응답의 상태를 나타낸다.
이는 클라이언트가 요청이 어떻게 처리되었는지를 쉽게 이해할 수 있게 도와준다.
아래는 새 사용자를 성공적으로 생성한 경우, 서버는 '201 Created' 상태 코드를 반환한다.

HTTP/1.1 201 Created

버전 관리
API가 변경되더라도 기존 클라이언트가 문제 없이 동작할 수 있도록, API에 버전 정보를 포함시킨다.
아래는 URI에 버전을 포함시키는 방법이다.

GET api/v1/users

HATEOAS(Hypertext As The Engine Of Application State)
서버 응답에 다음 가능한 작업에 대한 정보를 포함시키는 원칙입니다. 이를 통해 클라이언트는 서버 응답을 통해 다음에 할 수 있는 작업을 파악할 수 있습니다.
아래는 사용자 정보를 반환하는 응답에 사용자를 삭제하는 링크를 포함시키는 예시입니다.

GET /users/1
{
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "links": [
        {
            "rel": "delete",
            "href": "/users/1"
        }
    ]
}

RESTful

RESTful은 REST 원칙을 준수하는 웹 서비스를 가리키는 용어이다.
REST API를 제공하는 웹 서비스를 RESTful하다고 할 수 있다.
RESTful 웹 서비스는 클라이언트가 HTTP 메소드를 통해 서버의 자원을 손쉽게 이용할 수 있게 해준다.
RESTful은 REST를 REST답게 쓰기 위한 방법으로, 누군가가 공식적으로 발표한 것이 아니다. 즉, REST 원리를 따르는 시스템은 RESTful이란 용어로 지칭된다.

RESTful의 목적

이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것
RESTful한 API를 구현하는 근본적인 목적이 성능 향상에 있는 것이 아니라 일관적인 컨벤션을 통한 API의 이해도 및 호환성을 높이는 것이 주 동기이니, 성능이 중요한 상황에서는 굳이 RESTful한 API를 구현할 필요는 없다.