RESTful Architecture & API Design

1. Overview

RESTful 아키텍처 및 API 설계(RESTful Architecture & API Design, RAD)는 시스템 내부의 복잡한 데이터를 전 세계 하드웨어가 쉽게 이해할 수 있는 '명시적 리소스'로 변환하고, 이를 표준 규약에 맞춰 노출하는 소통의 미학이자 공학입니다.

학습자는 로이 필딩(Roy Fielding)이 정의한 REST의 6가지 핵심 제약 조건을 배웁니다. 특히, 명사 기반의 URI 설계 물리학과, 리소스의 현재 상태를 전달하는 **표현(Representation)**의 수리적 수순을 익힙니다. 또한, 클라이언트가 다음 행동을 서버로부터 응답받는 HATEOAS 개념과, 이를 업계 표준 문서로 만드는 OpenAPI/Swagger 설계 기법을 배웁니다. 이를 통해 서비스 간의 결합도를 물리적으로 낮추고, 수천 명의 개발자가 동시에 협업할 수 있는 명확한 소통로를 설계하는 하이엔드 API 아키텍처 역량을 확보합니다.

2. Scope & Boundaries

In-Scope

• REST Constraints: Client-Server, Stateless, Cacheable, Layered System, Code on Demand, Uniform Interface
• URI Physics: 계층적 리소스 구조 설계와 명사 중심의 수리적 명명 규칙
• HTTP Method Matching: 리소스 생명주기에 따른 메서드($CRUD$)의 물리적 정합성
• Content Negotiation: Accept 헤더를 통한 JSON, XML 등 상이한 표현 수리적 교환
• API Versioning: 시스템 진화에 따른 논리적 버전 관리 전략(URI vs Header)

Out-of-Scope

• 데이터베이스 스키마 설계 및 SQL 최적화 상세 (06-02-XX 영역에서 분담)
• gRPC나 GraphQL의 내부 수리 기제 (별도 특화 노드에서 분담 가능)

Boundaries

• RAD vs. HTTP Evolution: HPE(08-03-01)가 '차량의 엔진 전력량'에 집중한다면, RAD는 '차량이 실어나르는 화물의 분류와 규격'에 집중하여 아키텍처 계층을 구분합니다.

3. Counterexample

• 단순히 "URL 예쁘게 짓기"라 설명하는 것은 RAD 학습이 아닙니다. 왜 **멱등성(Idempotency)**을 지키지 않는 API 설계가 하드웨어 네트워크 유실 상황에서 '중복 결제'와 같은 치명적인 물리적 데이터 무결성 파괴를 일으키는지 수리적으로 증명할 수 있어야 하며, HATEOAS가 결여된 API가 왜 클라이언트와 서버 간의 물리학적 결합도($Coupling$)를 높여 독립적 진화를 방해하는지 논증하지 못한다면 REST의 정수를 이해하지 못한 것입니다.

4. Prerequisites

• HTTP & Protocol Evolution (Basic): HTTP 메서드 및 상태 코드의 물리학 이해가 필수입니다. (08-03-01 HPE)
• Data Structures & Algorithms (Recommended): 트리 구조 및 JSON 객체 수리 표현 이해가 권장됩니다. (04-01-XX)

5. Learning Map

1. The Resource Vision: 비즈니스 데이터를 '리소스'라는 독립적인 물리 실체로 바라보는 관점을 세웁니다.
2. Standardized Verbs: 리소스를 가공하는 동작(CRUD)을 약속된 어휘로 수리적으로 매핑합니다.
3. Hypermedia Drive: 문서 내에 다음 행동의 힌트를 담아 자동으로 소통하는 지능형 소통로(HATEOAS)를 형성합니다.
4. Contract First: 코드를 짜기 전 API 도면(OpenAPI)을 그려 시스템 간의 완벽한 물리적 합의를 완성합니다.

6. Learning Topics

Basic

Core: 리소스 중심 설계와 URI (Resource-Oriented URI)

• Why to Learn: 전 세계 개발자가 매뉴얼 없이도 API의 의도를 물리적으로 직관할 수 있게 하기 위해서입니다.
• What to Learn:
  • Resource Identification: '무엇'을 처리하는지에 집중하는 물리적 명명법
  • URI Structure: 하위 리소스와 컬렉션의 계층적 배치 수순
  • Naming Convention: 케밥 케이스($Kebab$) 등 업계 표준 물리 규칙
• How to Learn:
  • 복잡한 쇼핑몰 도메인을 보고 GET /orders/123/items와 같은 수리적 리소스 지도를 그려보는 실습
  • 동사 중심 명명(예: /deleteOrder)을 명사 중심(DELETE /orders)으로 변환하는 물리학적 정제
• Implement: 리소스 경로를 입력받아 표준 형식에 따라 파싱하고 유효성을 검사하는 기초 URIDissector

Recommended

Core: HTTP 메서드와 상태 코드 매칭 (Method & Status Matching)

• Why to Learn: 오류 발생 시 하드웨어가 스스로 대처하거나 개발자가 문제를 정확히 짚어내기 위함입니다.
• What to Learn:
  • Safe & Idempotent: 조회와 수정의 물리적 안전성 수리 정의
  • 2xx/4xx/5xx Codes: 상황에 따른 표준 응답의 하드웨어적 후속 처리
  • Status Mapping: 권한 부족(403)과 인증 실패(401)의 수리적 구분
• How to Learn:
  • 다양한 에러 상황을 연출하고, 서버가 뱉어야 할 가장 적절한 상태 코드를 논리적으로 매칭하는 실습
  • POST와 PUT의 물리적 차이(생성 vs 전체교체)가 데이터베이스에 미치는 수리적 파장 분석
• Implement: 요청 결과에 따라 규정된 HTTP 상태 코드를 반환하는 API 핸들러 StatusDispatcher

Practical

Core: 데이터 표현과 협상 (Content Negotiation & JSON)

• Why to Learn: 각기 다른 하드웨어(iOS, Android, Web)가 자신에게 최적화된 포맷으로 데이터를 받게 하기 위해서입니다.
• What to Learn:
  • Accept Types: 클라이언트의 물리적 선호 포맷 전달 기제
  • Pagination Mechanics: 대용량 데이터를 '커서'나 '오프셋'으로 쪼개는 수리 모델
  • Filtering & Sorting: 쿼리 파라미터를 통한 데이터 물리 필터링
• How to Learn:
  • API 서버에 Accept: application/xml 요청을 날려 하드웨어가 어떻게 수리적으로 포맷을 전환하는지 관찰 실습
  • 대량 리스트 조회 시 페이징 처리 유무에 따른 하드웨어 메모리 점유율 수치 격차 측정
• Implement: 쿼리 파라미터에 따라 배열 데이터를 수리적으로 필터링하고 슬라이싱하는 APIPaginator

Advanced

Core: HATEOAS와 API 진화 (Advanced RESTfulness)

• Why to Learn: API 버전이 바뀔 때마다 앱을 재배포하지 않아도 되는 유연한 시스템을 구축하기 위함입니다.
• What to Learn:
  • Hypermedia as the Engine: 링크 정보를 통한 클라이언트 가이드 물리학
  • Versioning Strategies: URI 버전, 커스텀 헤더 버전의 물리적 트레이드오프
  • Rate Limiting: API 남용을 막는 하드웨어 리소스 보호 알고리즘
• How to Learn:
  • 응답 JSON 내에 _links 필드를 추가하여, 클라이언트가 하드코드된 URL 없이 다음 단계로 넘어가는 물리 과정 구현 실습
  • API 문서를 OpenAPI(YAML)로 명세하고, 물리적인 'Client SDK'가 자동 생성되는 과정 추적
• Implement: API 사용량($Quota$)을 트래킹하여 초과 시 429 상태를 뱉는 RateLimiter 프로토타입

7. Terminology

8. References

Primary

• [P1] CS2023 - NC/Networking and Communication (Information models / Network applications) — Information modeling requirements.
• [P2] SWEBOK v4.0 - Software Design / Software Structure and Architecture (Service-oriented architecture) — Structural context.

Secondary

• [Architectural Styles and the Design of Network-based Software Architectures] Roy Fielding — The original dissertation.
• [RESTful Web APIs] Leonard Richardson — Practical implementation patterns.

Industry

• [Microsoft: API Design Guide] — Comprehensive industry rules.
• [Google: API Design Guide] — Resource-oriented best practices.

9. Final Checklist

Primary

• '단일 인터페이스(Uniform Interface)' 제약 조건이 왜 API의 물리적 범용성을 확보하는지 철학적으로 설명 가능한가? (P1)
• 'Stateless' 제약이 위반되었을 때, 분산 서버 환경에서 발생할 수 있는 데이터 불일치 물리학을 기술할 수 있는 가? (P1)

Secondary

• '리소스 계층' 설계 시, 자식 리소스를 URI 경로에 포함시키는 논리적 기준을 수리적 연관성 관점에서 소통 가능한가?
• **멱등성(Idempotency)**을 보장하기 위한 서버측 '중복 요청 방지 토큰'의 수리적 생성 과정을 논증할 수 있는 가?

Industry

• 엔터프라이즈 환경에서 'API Versioning'을 헤더($Header$) 기반으로 처리할 때의 캐싱 하드웨어 효율성 문제점을 제안할 수 있는 가? (SFIA)
• 서비스 안정성을 위한 Throttling 정책 수립 시, 특정 클라이언트의 폭주가 물리적 백엔드 시스템 전체에 미치는 파장을 분석할 수 있는 가?