Restful API(Representational State Transfer API)는 웹 기반의 어플리케이션 프로그래밍 인터페이스로, 클라이언트와 서버 간의 통신을 단순하고 확장 가능하게 설계하는 원칙을 따릅니다. REST는 웹 서비스 디자인 패턴 중 하나로, HTTP 프로토콜을 사용하여 요청과 응답을 주고받습니다.
1. REST란 무엇인가?
REST의 핵심 개념은 리소스(Resource)이며, 클라이언트와 서버 간의 상호작용에서 리소스를 주고받는 방식에 초점을 맞춥니다. REST는 다음과 같은 원칙을 기반으로 합니다.
1.1 Representational(표현)
REST에서는 리소스가 가장 중요한 개념입니다. 리소스는 데이터, 객체 또는 시스템 내에서 유의미하게 식별되는 모든 것을 의미하며, 이를 식별하는 방식이 바로 URI(Uniform Resource Identifier)입니다. 하지만 클라이언트와 서버가 주고받는 것은 리소스 자체가 아니라 그 표현(Representation)입니다.
URI란?
URI는 리소스를 식별하는 표준화된 방식입니다. 웹에서 리소스는 문서, 이미지, 비디오, API 엔드포인트 등으로 다양하게 존재하며, URI를 통해 고유하게 식별하고 접근할 수 있습니다.
URI의 구성
- 스킴(Scheme): 리소스에 접근할 때 사용할 프로토콜 (
http,https,ftp등) - 리소스 식별자: 스킴 이후에 오는 부분으로 리소스의 위치 또는 식별자를 지정합니다.
예시
https://www.example.com:8080/docs/resource.txt?query=example#section1이 예시는 URL처럼 보이지만, 사실 URI는 URL과 URN을 포함하는 더 포괄적인 개념입니다.
URN이란?
URN(Uniform Resource Name)은 리소스의 변하지 않는 고유한 식별자입니다. URI가 리소스의 위치를 지정할 수도 있는 반면, URN은 특정 리소스가 어떤 환경에서도 동일한 식별자로 유지되도록 보장합니다.
URN의 기본 구조
urn:<NID>:<NSS>urn: 스킴으로 URN을 나타냅니다.NID: 네임스페이스 식별자로 특정 네임스페이스를 정의합니다.NSS: 네임스페이스 내에서 해당 자원의 고유 이름을 나타냅니다.
하지만 RESTful API에서는 보통 리소스를 위치시키는 것이 핵심이므로 URL을 주로 사용합니다.
표현(Representation)이란?
예를 들어, 클라이언트가 특정 사용자 정보를 요청하면 서버는 데이터베이스에서 정보를 가져오지만, 클라이언트에게 전달하는 것은 그 사용자의 표현입니다. 이 표현은 JSON, XML, HTML 같은 포맷으로 제공될 수 있으며, 같은 리소스라도 표현 형식은 다를 수 있습니다.
이 개념이 다소 추상적으로 느껴질 수 있으므로, 예제를 통해 보다 자세히 설명하겠습니다.
예제: 사용자 정보 요청
클라이언트가 특정 사용자 정보를 요청하면 서버는 데이터베이스에서 해당 정보를 가져옵니다. 하지만 서버가 클라이언트에게 전달하는 것은 데이터베이스의 원본 데이터가 아니라, 그 데이터를 특정한 형식(Representation)으로 변환한 결과물입니다.
예를 들어, 데이터베이스에 다음과 같은 사용자가 저장되어 있다고 가정해 봅시다:
| ID | 이름 | 이메일 |
|---|---|---|
| 123 | 홍길동 | gildong@example.com |
이제 클라이언트가 GET /users/123 요청을 보낸다면, 서버는 이 정보를 클라이언트가 이해할 수 있는 형식(JSON, XML, HTML 등)으로 변환하여 전달합니다.
JSON 형식 (Representation)
{
"id": 123,
"name": "홍길동",
"email": "gildong@example.com"
}XML 형식 (Representation)
<user>
<id>123</id>
<name>홍길동</name>
<email>gildong@example.com</email>
</user>HTML 형식 (Representation)
<html>
<body>
<h1>사용자 정보</h1>
<p>ID: 123</p>
<p>이름: 홍길동</p>
<p>이메일: gildong@example.com</p>
</body>
</html>같은 리소스(사용자 정보)라도 클라이언트의 요청 방식에 따라 표현 형식(Representation)이 달라질 수 있습니다. 예를 들어, Accept: application/json 헤더를 포함하여 요청하면 JSON 형식으로 응답을 받고, Accept: application/xml 헤더를 포함하면 XML 형식으로 응답을 받을 수도 있습니다.
즉, 클라이언트가 받는 것은 데이터베이스의 원본 데이터가 아니라, 그 데이터를 특정 형식으로 가공한 표현(Representation)이라는 점이 REST의 중요한 개념 중 하나입니다.
1.2 State(상태)
REST에서 상태는 클라이언트와 서버 간의 상호작용에서 주고받는 리소스의 상태를 의미합니다. 클라이언트는 서버로 요청을 보내고 서버는 그 요청에 맞는 리소스의 표현을 반환합니다. 클라이언트는 이를 통해 리소스의 상태를 변경하거나 조회할 수 있습니다.
예를 들어, 클라이언트가 특정 상품 정보를 요청하면 서버는 현재 상품의 가격과 재고 상태를 반환할 수 있으며, 클라이언트가 특정 데이터를 전송하면 서버에서 해당 리소스의 상태가 변경될 수도 있습니다.
1.3 Transfer(전송)
REST는 상태의 표현을 클라이언트와 서버 간에 전송하는 개념을 기반으로 합니다. 즉, 클라이언트가 서버에게 리소스의 상태를 요청하면 서버는 그 리소스의 표현을 클라이언트에게 전송하는 방식입니다.
이 과정에서 HTTP 프로토콜의 GET, POST, PUT, DELETE, PATCH 같은 메서드를 사용하여 요청을 주고받습니다.
HTTP 메서드 개요
- GET: 데이터를 조회 (예:
GET /products→ 모든 상품 목록 반환) - POST: 새로운 리소스 생성 (예:
POST /products→ 새로운 상품 추가) - PUT: 기존 리소스 수정 (예:
PUT /products/123→ ID 123번 상품 정보 수정) - DELETE: 특정 리소스 삭제 (예:
DELETE /products/123→ ID 123번 상품 삭제) - PATCH: 리소스의 일부만 수정 (예:
PATCH /users/123→ 특정 필드만 업데이트)
2. REST의 핵심 원리
RESTful API는 다음과 같은 원칙을 따릅니다.
2.1 클라이언트-서버 구조
클라이언트와 서버는 서로 독립적으로 동작하며, 서로의 내부 구조를 알 필요가 없습니다. 클라이언트는 요청을 보내고 서버는 해당 요청에 맞는 응답을 제공합니다.
예시
웹 브라우저(클라이언트)에서 https://example.com/products/111과 같은 URL로 요청을 보내면 서버는 111번 상품의 정보를 반환합니다. 클라이언트는 서버의 내부 구현을 몰라도 됩니다.
2.2 무상태성
서버는 클라이언트의 상태를 저장하지 않습니다. 각 요청은 독립적이며, 클라이언트는 요청마다 필요한 모든 정보를 포함해야 합니다.
예시
클라이언트가 https://example.com/login으로 로그인 요청을 보내면 서버는 인증 후 인증 토큰을 반환합니다. 이후 클라이언트는 모든 요청에 인증 토큰을 포함해야 합니다.
2.3 캐시 가능성
서버는 응답에 캐싱 여부를 나타낼 수 있으며, 클라이언트는 이를 캐싱하여 동일한 요청을 반복해서 보내지 않고 저장된 데이터를 사용할 수 있습니다.
예시
클라이언트가 https://api.example.com/products/11로 상품 정보를 요청할 때 서버가 Cache-Control: max-age=3600을 응답하면, 클라이언트는 1시간 동안 캐시된 데이터를 사용할 수 있습니다.
2.4 계층화 시스템
클라이언트와 서버 간의 통신은 여러 계층으로 나눌 수 있으며, 이는 보안, 로드 밸런싱 등의 기능을 쉽게 구현하는 데 도움이 됩니다.
예시
사용자가 https://api.example.com/products/111로 요청을 보내면, 이 요청은 프록시 서버를 통과하여 보안 검사를 받고, 로드 밸런서를 거쳐 여러 서버 중 하나에서 처리될 수 있습니다.
2.5 통일된 인터페이스
클라이언트와 서버 간의 상호작용은 일관된 인터페이스를 통해 이루어져야 합니다.
예시
GET /users/123: 특정 사용자의 정보를 조회POST /users: 새로운 사용자 생성PUT /users/123: 기존 사용자 정보 수정DELETE /users/123: 특정 사용자 삭제
RESTful API는 리소스의 표현을 JSON, XML 등의 형식으로 일관되게 주고받으며, 이를 통해 클라이언트와 서버 간의 데이터 교환을 효율적으로 수행합니다.
2.6 HTTP 상태 코드
RESTful API 응답에는 HTTP 상태 코드가 포함됩니다. 대표적인 상태 코드는 다음과 같습니다.
- 200 OK: 요청이 성공적으로 처리됨
- 201 Created: 새로운 리소스가 생성됨
- 204 No Content: 요청이 성공했으나 응답 본문이 없음
- 400 Bad Request: 잘못된 요청
- 401 Unauthorized: 인증이 필요함
- 403 Forbidden: 접근 권한 없음
- 404 Not Found: 요청한 리소스를 찾을 수 없음
- 500 Internal Server Error: 서버 오류 발생
이러한 상태 코드를 적절히 사용하면 클라이언트가 API 응답을 더 효과적으로 처리할 수 있습니다.
