REST API

REST는 두 시스템 간의 통신을 위한 아키텍처 스타일로, Representational State Transfer의 약자이다. REST API는 REST 스타일을 사용하여 구현된 API를 부르는 명칭이다.

REST는 2000년 로이 필딩(Roy Fielding)의 논문에서 제안되었는데, 핵심은 단순하다.

리소스를 URI로 표현하고, 상태의 전송을 HTTP로 수행한다.

다시 말해, REST는 “무엇을 요청할지”와 “어떻게 요청할지”를 구분하여 표현하는 규칙으로, 웹상의 자원을 URI로 정의하고, GET, POST, PUT, DELETE 등의 HTTP 메소드를 사용해 자원의 상태를 주고받는 식으로 클라이언트와 서버가 정해진 규칙에 따라 서로 요청과 응답을 주고받도록 한다.

REST API의 핵심요소

리소스 (Resource)

리소스는 사용자, 게시글, 주문 등 서버가 다루는 모든 데이터를 의미하며, 고유한 식별자인 URI를 가진다.

GET /users
GET /posts/42

HTTP 메소드

REST는 HTTP 메소드를 이용해 리소스에 대해 수행할 동작을 나타낸다.

일반적인 CRUD(Create, Read, Update, Delete) 작업이 아래와 같이 각 메소드로 표현된다.

GET: 조회(Read) — 리소스를 가져온다
POST: 생성(Create) — 새로운 리소스를 만든다
PUT: 전체 수정(Update) — 리소스 전체를 덮어쓴다
PATCH: 일부 수정(Update) — 리소스의 일부를 변경한다
DELETE 삭제(Delete) — 리소스를 제거한다

// 새로운 사용자 리소스를 만든다.
POST /users

// 생성되어 있는 사용자 리소스를 조회한다
GET /users/1

표현 (Representation)

자원의 상태를 나타내는 정보의 형식으로 REST API는 일반적으로 JSON을 사용한다.

요청

POST /users
Content-Type: application/json

{
  "name": "Lucas",
  "email": "clee0627@gmail.com"
}

응답

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 1,
  "name": "Lucas",
  "email": "clee0627@gmail.com"
}

REST의 특징과 장점

Server-Client 구조: 서버와 클라이언트로 이루어진 구조를 가지며 둘은 서로 독립적으로 개발될 수 있다. 이로 인해 시스템의 확장 및 변경이 용이하다.
인터페이스 일관성 (Uniform Interface): 요청의 의미는 HTTP 메서드/상태코드/하이퍼미디어로 일관되게 전달된다.** **API의 명확한 요청과 응답 구조 덕분에 개발자들이 API를 이해하고 사용하며 유지보수하기가 용이하다.
계층화 (Layered System): 클라이언트와 서버 간의 통신을 여러 계층으로 분리하여 클라이언트가 실제 서버를 직접 알지 못하게 한다. 이 과정에서 클라이언트는 중간 계층(캐시, 게이트웨이)이 있음을 신경 쓸 필요가 없으며 이를 통해 확장성, 유연성, 보안성을 높인다.
무상태 (Statetless): 서버는 클라이언트 상태를 유지하지 않으며 각 요청은 필요한 모든 정보를 담아야 한다. 상태를 서버가 기억할 필요가 없으므로 서버 확장성과 가용성이 좋다.

단점과 한계

REST는 규칙이 단순하고 명확하기 때문에 많이 사용되지만 아키텍처 스타일일 뿐 엄격한 표준 규약이 존재하지는 않는다. 그래서 개발자의 역량이나 관점에 따라 다르게 설계될 수 있고 REST의 기본 원칙을 지키지 않고도 REST API 처럼 사용되는 안티패턴이 적용될 가능성이 높다.

또한 요청과 응답으로 이루어진 구조상 관계 데이터가 복잡할 경우 반복해서 요청을 해야하거나 실시간으로 변경되는 데이터를 지속적으로 처리해야하는 경우에는 맞지 않는다. 그래서 최근에는 GraphQL, gRPC, WebSocket API 같은 다른 접근법이 함께 사용된다.

RESTful

앞서 말했듯 REST는 엄격한 표준 규약이 있지 않기 때문에 안티패턴이 적용되기 쉽다. 그래서 REST 아키텍처 원칙을 최대한 잘 실천하는 것을 “RESTful”이라고 표현한다.

단순히 HTTP 메소드를 사용하고 URI로 리소스 관계를 나타냈다고 RESTful 한 것이 아닌데, REST 아키텍처 원칙을 잘 따르기 위해서는 리소스 중심 설계, 무상태성, 일관된 인터페이스, 그리고 하이퍼미디어(HATEOAS) 같은 개념이 잘 지켜져야 한다.

HATEOAS (Hypermedia As The Engine Of Application State)

HATEOAS는 REST 원칙 중 일관된 인터페이스를 지킬 수 있도록 하기 위해 나온 개념으로 기본적인 아이디어는 하이퍼미디어를 어플리케이션의 상태를 관리하기 위한 수단으로 사용하는 것이다.

더 쉽게 표현하면, 서버가 응답에 다음 가능한 행동(상태 전환)을 나타내는 하이퍼링크(링크 메타데이터)를 포함시켜 클라이언트가 스스로 어플리케이션의 흐름을 발견하도록 하는 방법으로 클라이언트는 서버 응답에서 어떤 URL을 호출해야 다음 행동을 할 수 있는지에 대해 파악할 수 있다.

HATEOAS 개념의 의도

클라이언트-서버 계약을 느슨하게 만든다 — 서버가 가능한 행동을 링크로 제공하면, 클라이언트는 URL 규칙을 하드코딩하지 않아도 된다.
서버 수정, 유지관리에 유리 — 서버가 링크 구조를 바꿔도 클라이언트는 응답에 포함된 링크만 따르면 된다.
사용자 흐름(워크플로우)을 명시 — 현재 상태에서 어떤 행동이 허용되는지, 어떤 관계(예: cancel, next, approve)가 있는지 표현 가능. 서버 응답 예시

{
  "data": {
    "type": "articles",
    "id": "42",
    "attributes": {
      "title": "REST와 HATEOAS",
      "body": "..."
    }
  },
  "links": {
    "self": "/articles/42",
    "comments": "/articles/42/comments",
    "author": "/users/7"
  },
  "actions": {
    "edit": {
      "method": "PATCH",
      "href": "/articles/42",
      "title": "Edit this article"
    },
    "delete": {
      "method": "DELETE",
      "href": "/articles/42"
    }
  }
}

즉, HATEOAS는 개발자가 복잡한 API 문서를 작성하고 그 내용과 규칙들을 클라이언트 쪽에서 모두 파악하고 있지 않아도 개발에 문제가 없도록 하여 REST 원칙을 따를 수 있게 해주는 방법이다.

[다시하는 백엔드 기초 공부] REST API