# 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. 계층 구조 표현
```http
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의 장점
1. **단순성**: HTTP 표준 기반으로 이해 및 구현 용이
2. **확장성**: 무상태 특성으로 서버 부하 분산 가능
3. **유연성**: 다양한 포맷(XML, JSON 등) 지원
4. **캐싱 효율성**: GET 요청 캐싱으로 성능 향상
5. **상태 독립성**: 서버 메모리 사용 최소화

## 보안 고려사항
1. **HTTPS 강제 사용**
   - 데이터 암호화로 중간자 공격 방지

2. **인증/인가**
   - API 키: `Authorization: API_KEY`
   - OAuth 2.0: 토큰 기반 인증
   - JWT: 클라이언트 측에 저장된 토큰 검증

3. **요청 제한(Rate Limiting)**
   - 과도한 요청 방지를 위해 시간당 요청 횟수 제한

4. **입력 검증**
   - SQL 인젝션, XSS 공격 방지를 위한 파라미터 검증

5. **로그 기록**
   - 오류 추적 및 보안 감사용 로그 저장

## 예시: 사용자 관리 API
### 요청
```http
GET /api/v1/users?role=admin HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Accept: application/json
```

### 응답
```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
}
```

# 스트리밍 오류

LLM 서비스에서 응답을 받을 수 없습니다.

## 관련 문서
1. [Fielding의 REST 아키텍처 논문](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
2. [HTTP 상태 코드 표준](https://developer.mozilla.org/ko/docs/Web/HTTP/Status)
3. [OAuth 2.0 프로토콜 설명](https://oauth.net/2/)
4. [JSON API 표준 문서](https://jsonapi.org/)

---

이 문서는 REST API의 기본 개념과 실무 적용 방법을 체계적으로 정리하여 웹 개발자들이 표준화된 API를 설계할 수 있도록 돕기 위해 작성되었습니다. 추가적인 사항은 관련 문서를 참조하시기 바랍니다.