1.4장: REST API 구조

학습 시간: 45분

1. REST API: 우주 정거장 아키텍처

각 모듈이 다음을 갖는 우주 정거장을 상상해 보세요:

표준 도킹 포트 (단일 인터페이스)
명확한 전문화 (주거 구역, 실험실, 저장고)
좌표계 (정확한 위치)

REST (Representational State Transfer) API는 동일한 원리로 작동합니다:

모든 리소스에 대한 단일 인터페이스
명확한 구성 요소 분리
URI를 통한 주소 지정 (우주 좌표)

💡 핵심 아이디어:

각 리소스(행성, 로켓, 우주 비행사)는 고유한 URL 주소를 가지며 HTTP 메서드를 통해 상호 작용합니다.

2. 우주 비유로 본 REST의 6가지 원칙

REST 원칙	ISS 비유	API에서의 의미
단일 인터페이스	표준 도킹 노드	모든 요청에 대한 동일한 규칙
무상태성(Stateless)	각 명령은 자체 포함적이다	서버는 클라이언트 상태를 저장하지 않는다
캐싱	현지 식량 비축량	자주 요청되는 응답 저장
클라이언트-서버	명확한 분리: 지상 관제소 ↔ 정거장	구성 요소의 독립적인 개발
계층화	중계 위성	프록시, 로드 밸런서
온디맨드 코드	실험용 소프트웨어 다운로드	(선택 사항) 스크립트 전송

3. 리소스 및 URI: 우주 좌표

API의 모든 객체는 고유한 주소를 가진 리소스입니다:

https://api.spacexdata.com/v4/    ← 기본 URL
          rockets/            ← 로켓 컬렉션
          rockets/5e9d0d95eda69973a809d1ec ← 특정 로켓 (ID로)

우주 리소스 예시:

GET /stars → 별 목록
GET /stars/sirius → 시리우스 데이터
POST /satellites → 새 위성 발사
PUT /missions/artemis → 미션 업데이트

URI 계층 구조:

[기본 URL]
├── /planets          → 행성 컬렉션
│   ├── /mars         → "화성" 리소스
│   └── /venus        → "금성" 리소스
└── /launches         → 발사 컬렉션
    ├── /upcoming     → 하위 컬렉션
    └── /latest       → 리소스

4. HTTP 메서드를 통한 CRUD 작업

작업	HTTP 메서드	예시 (우주 정거장)	서버 응답
생성(Create)	`POST`	새 모듈 전송	`201 Created`
읽기(Read)	`GET`	모듈 데이터 요청	`200 OK`
업데이트(Update)	`PUT`	모듈 재구성	`200 OK`
삭제(Delete)	`DELETE`	오래된 모듈 분리	`204 No Content`

⚡ 코드 예시 (위성 추가):

import requests

# 리소스 생성을 모방하는 테스트 서비스를 사용합니다.
new_post = {
    "title": "새 망원경 발사",
    "body": "허블-2가 배치 준비를 마쳤습니다.",
    "userId": 1
}

# 헤더 시연을 위한 가상 API 키
headers = {
    "Authorization": "Bearer YOUR_DEMO_KEY",
    "Content-Type": "application/json; charset=UTF-8"
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    headers=headers
)

if response.status_code == 201:
    print("✅ 새 위성에 대한 게시물이 성공적으로 생성되었습니다!")
    print("서버 응답:")
    print(response.json())
else:
    print(f"❌ 오류! 상태: {response.status_code}")

5. API 버전 관리: 정거장의 진화

ISS가 업데이트되는 것처럼(자랴 모듈 → 나우카), API도 버전을 변경합니다:

URL에서: https://api.spacex.com/v4/rockets
헤더에서: Accept: application/vnd.spacex-v5+json

중요한 이유:

v1: 기본 기능
v2: 새 필드 추가됨
v3: 응답 구조 변경됨

⚠️ 팁: 항상 요청에 버전을 지정하세요. 그렇지 않으면 "도킹"이 실패할 수 있습니다!

6. 하이퍼미디어 (HATEOAS): 우주에서의 내비게이션

API 응답에는 스테이션 지도처럼 관련 리소스에 대한 링크가 포함됩니다:

{
  "id": "iss",
  "name": "국제 우주 정거장",
  "crew": 7,
  "_links": {
    "self": { "href": "/stations/iss" },
    "modules": { "href": "/stations/iss/modules" },
    "schedule": { "href": "/stations/iss/schedule" }
  }
}

복습 퀴즈

🚀 장 요약:

REST API는 웹 서비스용 표준화된 "우주 정거장 아키텍처"입니다. 기억하세요:

리소스 = 객체 (로켓, 행성)
URI = 객체 좌표
HTTP 메서드 = 제어 명령
버전 = 정거장 현대화

준비 완료! 다음 장에서는 "테스트 프로브"를 발사할 것입니다. Postman을 통해 API를 테스트하는 방법을 배웁니다.

📌 실습: SpaceX API의 구조를 살펴보고 다음을 실행해 보세요:

GET https://api.spacexdata.com/v4/launches/latest — URI와 JSON 구조에 주목하세요!