[웹] REST API 기본 개념

Woonil·2026년 2월 4일

웹

목록 보기

9/9

REST 원칙이란 REST(REpresentational State Transfer) API 설계의 중심에는 자원(Resource)이 있고, 자원에 대한 행위(HTTP Method)를 통해 자원을 처리하도록 설계하는 것을 말한다.

이때, 자원(resource)은 이름을 지닐 수 있는 모든 정보 및 개념적인 대상을 의미한다.

ex) 문서, 이미지, 자원들의 집합, 실존하는 대상 등

구성요소
구성 요소 내용 표현 방법
Resource 자원 HTTP URI
Verb 자원에 대한 행위 HTTP Method
Representations 자원에 대한 행위의 내용 HTTP Message Payload

구성 요소	내용	표현 방법
Resource	자원	HTTP URI
Verb	자원에 대한 행위	HTTP Method
Representations	자원에 대한 행위의 내용	HTTP Message Payload

REST API란 REST 원칙을 적용하여 서비스 API를 설계하는 것이고, RESTful API는 REST 원칙을 잘 지켜서 설계한 API를 뜻한다.

API
프로그램끼리 통신할 수 있도록 하는 중재자

장점
- Open API를 제공하기 쉽다.
- 멀티 플랫폼 지원 및 연동이 용이하다.
- 원하는 타입으로 데이터를 주고 받을 수 있다.
- 기존 웹 인프라(HTTP)를 그대로 사용할 수 있다.
  
  HTTP는 Restful API의 필수요소는 아니지만, RESTful API의 조건을 구현하기 용이하기 때문에 현업에서 주로 사용된다.
단점
- 메서드로 수행할 수 있는 동작이 4가지(CRUD)로 한정된다.
- 분산 환경에는 부적합하다.

🤔개념

URI(Uniform Resource Identifier)

웹 상에서의 자원을 식별하기 위한 정보이다. 자원(Resource)을 식별(Identify)하는 통일(Uniform)된 방식으로 URI로 자원을 식별할 때는 ‘이름’ 또는 ‘위치’를 기반으로 식별한다.

URN(Uniform Resource Name): 이름으로 자원을 식별하는 방식
URL(Uniform Resourc Locator): 위치로 자원을 식별하는 방식으로, 오늘날 인터넷 환경에서 웹 주소로써 자원 식별에 많이 사용된다.

URL의 구조

구성	설명
scheme	자원에 접근하는 방법 (일반적으로 프로토콜)
authority	호스트를 특정할 수 있는 IP 주소나 도메인 네임
path	자원이 위치하고 있는 경로
query	URL에 대한 매개변수 역할을 하는 문자열로, 쿼리 문자열, 쿼리 파라미터 등으로 불린다. 각 쿼리는 `이름=값` 으로 명시되고, 쿼리들은 `&` 로 구분된다.
fragment	자원의 일부분을 가리키기 위한 정보

REST와 URI

REST에서 URI는 특정 요청이 ‘어떤 자원’에 관한 것인지 표현해야 하고 또 가능한 한 ‘그것만’ 표현해야 한다. 또한 자원으로 무엇을 ‘하는가’를 나타내는 동사는 URI에 가능한 한 포함하지 않으며, 자원이 가리키는 것은 명사로 표현되어야 한다.

GET https://api.example.com/v1/todos/1

요청의 메서드와 URI 자체가 그것의 목적을 명확히 나타낸다면, 개발자가 다른 팀과의 협업할 때나 공공 API를 처음으로 사용해야 할 때 큰 어려움 없이 새 API의 사용법을 익힐 수 있다.

네이밍 컨벤션

리소스명은 동사가 아닌 명사를 사용한다. 즉, get 같은 행위에 대한 표현은 URI에 포함하지 않는다.

자원에 대한 행위는 오로지 HTTP 메서드로 표현하며, 분명한 목적으로 사용해야 한다.

메서드	행위	목적	페이로드
GET	index/retrieve	모든/특정 리소스를 조회	x
POST	create	리소스를 생성	○
PUT	replace	리소스의 전체를 교체	○
PATCH	modify	리소스의 일부를 수정	○
DELETE	delete	모든/특정 리소스를 삭제	x

소문자를 사용해야 한다.
언더바(_) 대신 대시(-)를 사용한다.
파일 확장자는 포함하지 않는다.
마지막에 슬래시(/)를 포함하지 않는다.
(선택사항) API 버전을 관리한다.
- 환경은 항상 변하기 때문에 API의 signature가 변경될 수도 있음에 유의한다.
- 특정 API를 변경할 때는 반드시 하위 호환성을 보장해야 한다.

제약 조건

네이밍 컨벤션을 잘 지키는 것만으로는 RESTful하다고 말하지 못할 수 있다. 진정한 RESTful API가 되기 위해서 아래 6가지 스타일을 반드시 지켜야 한다.

Client-Server (클라이언트-서버 구조)

REST 서버는 API를 제공하고 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분된다. 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로 간 의존성이 줄어든다.

Stateless (무상태성)

HTTP는 stateless(무상태성)한 프로토콜이므로 HTTP 위에서 주로 동작하는 REST 또한 무상태성 성격을 갖는다. 다시 말해 작업을 위한 상태 정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 덕분에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순하다는 장점이 있다.

무상태성은 HTTP의 멱등성(idempotent)와도 관련이 있다. 이는 클라이언트가 같은 요청을 몇 번을 보내든 언제나 같은 응답이 돌아와야 한다는 특성이다. 정확하게는 실제 데이터가 바뀌었을 때를 제외하고, 첫 번째 작업을 수행한 뒤 여러 차례 적용해도 결과를 변경하지 않는 특성이라 할 수 있다. 멱등성을 지닌 HTTP 메서드로는 GET, PUT, DELETE 가 있다.

Caching (캐시 가능)

클라이언트와 서버는 서로에 대해서는 기억하지 않아야 하지만, 자신이 어떤 응답을 받았는지와 어떤 응답을 보냈는지는 기억해두는 것이 권장된다.

REST는 웹 표준인 HTTP를 그대로 사용하기 때문에 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있다. 이를테면, HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag 등을 이용하면 캐싱 구현이 가능하다.

Layered(Hierarchical) system (계층화)

REST 서버는 다중 계층으로 구성될 수 있으며, 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.

Uniform Interface

URI로 지정한 리소스에 대한 조작을 통일되고 한정적이고 일관된 인터페이스로 수행하는 아키텍처 스타일을 말한다.

Identification of Resources: 자원을 객체로 보며, 이때 객체는 시간이 지남에 따라 없었다가 생성되고 상태가 변화하고 파괴되어 없어진다는 특성을 지닌다. 따라서 특정한 객체를 식별하기 위해서는 해당 객체의 현재 상태를 보는 것만으로는 부족하고, 개별 객체에 대해 언제나 변하지 않는 불변값(고유한 식별자)를 부여해야 한다. 결국 서버의 개별 자원에 대한 고유한 식별자로 고유한 URI를 사용해야 한다는 의미이다.
Manipulation of Resources through Representations: 표현(representations)은 ‘특정한 상태의 자원에 대한 표현’을 의미한다.
Self-descriptive messages(자체 표현 메시지): 클라이언트와 서버 사이에 존재하는 중개자들에게 메시지의 내용을 어떻게 처리해야 하는 지에 대해 제대로 설명해야 한다. ex) host 헤더
HATEOAS(Hypermedia as the Engine of Application State): 각 요청의 응답에 가용한 다른 요청들의 정보를 포함시키는 것이다. 해당 정보를 통해서 개발자는 API 문서들을 모두 뒤져보지 않아도 다음에 어떤 요청을 보낼 수 있는지 살펴볼 수 있다. 또한 API의 세부 사항이 변경되더라도 클라이언트에서 이 정보를 참조하게 만들면 클라이언트의 코드를 수정할 필요가 없어진다.
```
// 출처: 유튜브 얄팍한 코딩사전
{
  "id": 1,
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "published_date": "2008-08-01",
  "isbn": "9780132350884",
  "status": "available",
  "links": [
    { "rel": "self", "href": "https://api.yalcobooks.com/v1/books/1" },
    { "rel": "update", "href": "https://api.yalcobooks.com/v1/books/1" },
    { "rel": "delete", "href": "https://api.yalcobooks.com/v1/books/1" }
  ]
}
```
파스타를 주문했을 때, 파스타를 갖다주면서 커피와 디저트 메뉴판을 같이 주는 것을 떠올려보자.
[출처: 유튜브 얄팍한 코딩사전]

Code-on-demand

REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다.

구성요소
- 자원: URI를 이용하여 표현
- 행위: HTTP 메서드를 이용하여 표현

참고자료
REST API - 이거 하나로 끝남
[10분 테코톡] 정의 REST API
Day1, 2-2. 그런 REST API로 괜찮은가

Woonil

프론트 개발과 클라우드 환경에 관심이 많습니다:)

이전 포스트