REST API
REST API
개요
REST API(Representational State Transfer Application Programming Interface)는 웹 서비스 개발에서 널리 사용되는 아키텍처 스타일로, 클라이언트-서버 간의 데이터 통신을 단순화하고 확장성을 높이기 위해 설계되었습니다. Roy Fielding이 2000년에 발표한 박사 논문에서 처음 정의된 이 개념은 HTTP 프로토콜의 표준 메서드와 상태를 기반으로 하여 현대 웹 개발의 핵심 기술로 자리 잡았습니다. 이 문서는 REST API의 핵심 원칙, HTTP 메서드, 리소스 네이밍 규칙, 장점, 보안 고려사항 및 실제 예시를 다룹니다.
REST API의 핵심 원칙
REST는 6가지 주요 제약 조건을 기반으로 설계되었습니다.
1. 클라이언트-서버 아키텍처
- 서버: 리소스를 관리하고 제공
- 클라이언트: 리소스 요청 및 표현 처리
- 역할 분리로 인해 시스템 유연성과 확장성이 향상됩니다.
2. 무상태(Stateless)
- 모든 요청은 서버가 이전 요청 정보 없이 독립적으로 처리할 수 있도록 전체 정보를 포함해야 합니다.
- 예시: 세션 정보는 클라이언트 측에서 관리 (JWT 토큰 사용)
3. 캐시 가능(Cacheable)
- 서버 응답에 캐시 가능 여부를 명시하여 클라이언트 캐시 활용도 증대
- 성능 최적화 및 네트워크 트래픽 감소
4. 계층화 시스템(Layered System)
- 프록시, 게이트웨이 등 중간 계층 추가 가능
- 보안, 로드 밸런싱, 캐싱 등 확장 기능 구현에 유리
5. 통일된 인터페이스(Uniform Interface)
REST의 핵심 특성으로 4가지 하위 원칙 포함:
1. 리소스 식별: URI로 리소스 식별 (예: /api/users/1)
2. 리소스 조작: 리소스 자체가 포함된 표현으로 조작
3. 자가 기술적 메시지(Self-descriptive Messages): HTTP 메서드, 헤더, 상태 코드 포함
4. 하이퍼미디어(HATEOAS): 응답에 다음 가능한 작업 링크 포함
6. 코드 온 디맨드(Optional)
- 서버에서 실행 가능한 코드(예: JavaScript)를 클라이언트에 전송 가능 (선택적)
HTTP 메서드
REST API는 HTTP 표준 메서드를 활용하여 리소스 조작을 정의합니다.
| 메서드 | 설명 | 예시 URI |
|---|---|---|
| GET | 리소스 조회 (안전한 메서드) | /api/users |
| POST | 새 리소스 생성 (비멱등성) | /api/users |
| PUT | 리소스 전체 수정 (멱등성) | /api/users/1 |
| PATCH | 리소스 일부 수정 (멱등성) | /api/users/1 |
| DELETE | 리소스 삭제 (멱등성) | /api/users/1 |
| HEAD | GET 응답의 헤더만 반환 | /api/users |
| OPTIONS | 지원되는 메서드 목록 반환 | /api/users |
멱등성(Idempotent): 동일한 요청을 여러 번 보내도 결과가 동일해야 한다는 특성
리소스 네이밍 규칙
URI 설계 시 지켜야 할 관행:
1. 명사 중심
- X:
/getUsers - O:
/api/users
2. 복수형 사용
/api/products(단수형 사용 금지)
3. 계층 구조 표현
GET /api/companies/123/employees/456
4. 쿼리 파라미터 활용
- 필터링:
GET /api/users?role=admin - 정렬:
GET /api/users?sort=-created_at
5. 버전 관리
/api/v1/users(URI에 API 버전 명시)
REST API의 장점
- 단순성: HTTP 표준 기반으로 이해 및 구현 용이
- 확장성: 무상태 특성으로 서버 부하 분산 가능
- 유연성: 다양한 포맷(XML, JSON 등) 지원
- 캐싱 효율성: GET 요청 캐싱으로 성능 향상
- 상태 독립성: 서버 메모리 사용 최소화
보안 고려사항
- HTTPS 강제 사용
-
데이터 암호화로 중간자 공격 방지
-
인증/인가
- API 키:
Authorization: API_KEY - OAuth 2.0: 토큰 기반 인증
-
JWT: 클라이언트 측에 저장된 토큰 검증
-
요청 제한(Rate Limiting)
-
과도한 요청 방지를 위해 시간당 요청 횟수 제한
-
입력 검증
-
로그 기록
- 오류 추적 및 보안 감사용 로그 저장
예시: 사용자 관리 API
요청
GET /api/v1/users?role=admin HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Accept: application/json
응답
{
"data": [
{
"id": "123",
"name": "홍길동",
"role": "admin",
"links": [
{"rel": "self", "href": "/api/v1/users/123"},
{"rel": "delete", "href": "/api/v1/users/123", "method": "DELETE"}
]
}
],
"total": 1,
"page": 1,
"limit": 10
}
관련 문서
이 문서는 REST API의 기본 개념과 실무 적용 방법을 체계적으로 정리하여 웹 개발자들이 표준화된 API를 설계할 수 있도록 돕기 위해 작성되었습니다. 추가적인 사항은 관련 문서를 참조하시기 바랍니다.
이 문서는 AI 모델(qwen-3-235b-a22b)에 의해 생성된 콘텐츠입니다.
주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.