REST API는 무엇일까요?
API 개발을 하다보면 항상 듣는 용어
REST API는 무엇일까요?REST API는
Representational State Transfer의 약자로 네트워크를 통해 클라이언트와 서버 간의 상호작용을 위한 규칙과 원칙을 정의한 아키텍처 스타일입니다.REST API는 HTTP 프로토콜을 기반으로 하여 클라이언트가 특정 리소스에 접근할 수 있도록 하고 이 리소스는 일반적으로 JSON 형식의 데이터를 통해 표현됩니다.
리소스는 URL을 통해 고유하게 식별되며 클라이언트는 이 URL에 HTTP 메서드(
GET, POST, PUT, DELETE 등)를 사용해 요청을 보내고 서버는 요청에 대한 응답을 반환하는 방식으로 동작합니다.여기까지는 REST API에 대해 조금이라도 들어보았다면 알 수 있는 내용입니다. 그럼 조금 더 자세하게 파헤쳐 보겠습니다.
그럼
RESTful API는 뭔가요?RESTful API는 REST API 원칙을 실제로 적용하여 개발한 API라고 생각하면 이해가 쉽습니다.
REST API가 가이드라면 RESTful API는 실제 가이드대로 개발한 API인 것이죠.
REST API의 구조
REST API는 규칙과 원칙을 정의한 아키텍쳐 스타일이라고 하였는데 그럼 어떤 구조로 이루어져 있을까요?
크게
자원, 행위, 표현으로 REST API의 구조를 나타낼 수 있습니다.자원(Resource) - URI
자원은 REST API에서 관리하고자 하는 대상입니다.
사용자, 게시글, 제품 등과 같은 실체를 가리키며 자원은 서버에 의해 고유하게 식별됩니다. 각 자원은 하나의 URI(Uniform Resource Identifier)로 나타냅니다.
URI예시
https://fabric0de.com/user→ 사용자 전체를 의미하는 URI로 USER은 Collection 자원
https://fabric0de.com/user/1→ 특정 사용자를 나타내는 URI로 1은 Collection 리소스의 단일 자원인 Element 자원
URL과 URI?
URI는 인터넷 상의 자원을 식별하기 위한 모든 문자열을 말하고 URL은 자원의 위치를 식별할 수 있는 URI의 한 형태다. 쉽게 말해 모든 URL은 URI이지만 모든 URI가 URL은 아니다.행위(Verb) - HTTP METHOD
HTTP 메서드는 클라이언트가 서버에 요청할 때 수행할 작업을 정의합니다.
REST API는 주로 HTTP 메서드를 사용하여 CRUD(
Create, Read, Update, Delete) 작업을 수행합니다.표현(Representations)
표현은 서버에서 클라이언트로 자원을 전달하는 방식이다.
표현은 주로
JSON이나 XML 형식으로 이루어지며 클라이언트는 이 표현을 통해 자원의 상태나 데이터를 받는다. 표현은 자원의 속성, 관계 등을 포함할 수 있다.{ "id": 1, "name": "JUNG HYEON", "email": "junghyeonkim.dev@gmail.com" }
REST원칙의 특징과 장단점
REST원칙의 특징과 장단점은 아래 내용과 같습니다.
1. 일관된 인터페이스 (Uniform Interface)
REST API는 특정한 표준을 따르는 일관된 인터페이스를 제공합니다. 이러한 인터페이스를 통해 API 사용이 쉬워지고 확장성이 증가합니다. 주요 특징 다음과 같습니다.
- 리소스 식별 (Resource Identification)
- 각 리소스는 고유한
URI(Uniform Resource Identifier)를 가집니다. - 예:
GET /users/1→ ID가 1인 사용자 정보 조회
- 표현과 리소스 분리 (Representation & Resource Separation)
- 클라이언트는 서버의 데이터 구조를 알 필요 없이
JSON, XML등 다양한 형식으로 데이터를 받을 수 있습니다. - 예:
Content-Type: application/json
- HTTP 표준 메서드 사용
- REST API는 HTTP 메서드를 활용하여 리소스를 조작합니다.
GET→ 데이터 조회POST→ 새로운 데이터 생성PUT→ 기존 데이터 전체 수정PATCH→ 기존 데이터 일부 수정DELETE→ 데이터 삭제
2. 캐시 가능 (Cacheable)
REST API의 응답(Response)은 캐싱이 가능해야 합니다. HTTP의
Cache-Control 또는 ETag를 활용하여 응답을 캐시할 수 있습니다. 불필요한 요청을 줄여 성능을 향상시키고 서버의 부하를 줄일 수 있습니다.3. 무상태성 (Stateless)
서버는 클라이언트의 이전 요청 상태를 저장하지 않습니다. 각 요청(Request)은 독립적이며 필요한 모든 정보를 포함해야 합니다. 이로 인해 서버의 확장성이 증가하고 요청이 어디에서 오든 동일한 결과를 보장할 수 있습니다. 예를 들어, 인증을 위해 매 요청마다
토큰(Token)을 포함해야 합니다.4. 클라이언트-서버 구조 (Client-Server Architecture)
클라이언트(Client)와 서버(Server)의 역할이 명확히 분리됩니다. 클라이언트는 사용자 인터페이스(UI)와 사용자 경험(UX)을 담당하며 서버는 데이터 저장과 비즈니스 로직을 처리합니다. 이로 인해 클라이언트와 서버의 독립적인 개발 및 유지보수가 용이합니다.5. 계층화된 시스템 (Layered System)
REST API는 여러 개의 계층(Layer)으로 구성될 수 있으며 각 계층은 독립적으로 동작합니다.
예를 들어, 클라이언트는 API가 직접 데이터베이스와 통신하는지 혹은 중간에 프록시나 로드 밸런서가 있는지 알 필요가 없습니다. 이러한 계층 구조는 보안 및 확장성에 유리합니다.
6. 자체 표현 구조(Self-descriptiveness)
REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다는 것입니다. REST API에서는 각
요청(Request)과 응답(Response)이 자체적으로 이해할 수 있는 구조를 가져야 합니다. 이를 통해 추가적인 문서나 설명 없이도 API 메시지 자체만 보고도 의미를 파악할 수 있어야 합니다.7. 코드 온 디맨드 (Code on Demand) (선택적)
대부분의 REST API에서 사용되지 않지만 필요하면 서버에서 클라이언트로 실행 가능한 코드(예: JavaScript)를 전송할 수 있습니다.
REST API의 장점
✅확장성(Scalability) → 무상태성 덕분에 서버 확장이 용이함
✅유연성(Flexibility) → JSON, XML 등 다양한 데이터 형식 지원
✅보안(Security) → HTTPS, 인증 토큰(JWT, OAuth 등) 사용 가능
✅캐시 지원(Cacheability) → 성능 최적화 가능
✅표준 HTTP 사용 → 다양한 플랫폼과 쉽게 연동 가능
REST API의 단점
❌ 과다한 데이터 전송(Over-fetching & Under-fetching) → 필요한 데이터만 받을 수 없음
❌ API 설계가 어렵고 일관성을 유지하기 어려움
❌ 실시간 통신에 부적합 → WebSocket 같은 프로토콜이 더 적합함
REST API 디자인 가이드
잘 설계된 REST API는 위에 특징들을 참고한 일관성, 확장성, 유지보수성을 갖추어야 합니다.
REST API URL 설계 (Endpoints & Naming)
1. 명사를 사용한 리소스 설계
- REST는 리소스 중심으로 설계되어야 하므로 URL에는 동사가 아니라 명사를 사용해야 합니다.
- HTTP 메서드를 사용하여 동작을 표현합니다.
✅ 올바른 예시 GET /users → 모든 사용자 조회 GET /users/{id} → 특정 사용자 조회 POST /users → 사용자 생성 PUT /users/{id} → 사용자 전체 수정 PATCH /users/{id} → 사용자 일부 수정 DELETE /users/{id} → 사용자 삭제 🚫 잘못된 예시 GET /getUser POST /createUser DELETE /deleteUser
2. 계층적 구조를 활용한 URL 설계
- 리소스 간의 관계를 URL 경로로 표현할 수 있습니다.
- 너무 깊은 경로는 유지보수성을 떨어뜨리기 떄문에 꼭 필요한 경우가 아니라면 지양합니다.
✅ 올바른 예시 GET /users/{id}/orders → 특정 사용자의 주문 목록 조회 GET /products/{id}/reviews → 특정 상품의 리뷰 목록 조회 🚫 잘못된 예시 GET /users/{id}/orders/{order_id}/items/{item_id}
3. 복수형(Plural) 사용
RESTful API의 리소스는 컬렉션을 의미하기 때문에 복수형을 사용해야 합니다.
✅ 올바른 예시 /users, /products, /orders 🚫 잘못된 예시 /user, /product, /order (단수형은 지양)
4. 필터링, 정렬, 페이징(Query Parameters)
- 대량의 데이터를 다룰 때는 쿼리 파라미터를 사용하여 필터링, 정렬, 페이징을 적용합니다.
✅ 필터링 (Filtering) GET /products?category=electronics&brand=samsung ✅ 정렬 (Sorting) GET /products?sort=price_asc ✅ 페이징 (Pagination) GET /products?page=1&size=20
HTTP 메서드 활용 (CRUD 매핑)
- REST API는 HTTP 메서드를 활용하여 요청의 목적을 나타냅니다.
HTTP 메서드 | 목적 | 예시 |
GET | 데이터 조회 | GET /users (모든 사용자 조회) |
POST | 데이터 생성 | POST /users (새 사용자 생성) |
PUT | 데이터 전체 수정 | PUT /users/{id} (전체 정보 업데이트) |
PATCH | 데이터 일부 수정 | PATCH /users/{id} (일부 정보 업데이트) |
DELETE | 데이터 삭제 | DELETE /users/{id} (사용자 삭제) |
상태 코드 (HTTP Status Code)
REST API 응답에서는 적절한 HTTP 상태 코드를 반환해야 합니다.
상태 코드 | 의미 | 설명 |
200 OK | 성공 | 요청이 정상적으로 처리됨 |
201 Created | 리소스 생성됨 | POST 요청 후 새로운 리소스가 생성됨 |
204 No Content | 성공, 응답 없음 | 요청이 성공했지만 반환할 데이터 없음 |
400 Bad Request | 잘못된 요청 | 요청 형식이 올바르지 않음 |
401 Unauthorized | 인증 필요 | 인증되지 않은 사용자 |
403 Forbidden | 접근 금지 | 권한 부족 |
404 Not Found | 리소스 없음 | 요청한 리소스를 찾을 수 없음 |
409 Conflict | 중복 발생 | 리소스 충돌 (예: 중복된 데이터) |
500 Internal Server Error | 서버 오류 | 서버에서 예상치 못한 오류 발생 |
응답 형식 (Response Format)
REST API의 응답은 JSON(JavaScript Object Notation) 형식을 사용하는 것이 일반적입니다.
{ "id": 1, "name": "John Doe", "email": "john.doe@example.com", "createdAt": "2024-02-09T12:34:56Z" }
REST API 보안
1. 인증 및 권한 관리
- JWT (JSON Web Token) 또는 OAuth 2.0을 활용하여 인증 처리
- API 키 또는 토큰을
Authorization헤더에 포함
Authorization: Bearer {TOKEN}
2. CORS (Cross-Origin Resource Sharing) 설정
- API 호출을 특정 도메인에서만 허용하도록 설정
Access-Control-Allow-Origin을 통해 허용할 도메인 지정
Access-Control-Allow-Origin: https://example.com
3. 입력 검증 및 보안 강화
- SQL Injection, XSS, CSRF 방지
- 요청 데이터의 유효성 검사 수행
