김신건의 로그 - 위키 / api-design

[API Design] API Versioning: URL / Header / Date 비교

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

API Versioning 은 breaking change 를 클라이언트에 강요 없이 호환성을 유지하는 전략. 잘못 잡으면 모든 클라이언트 동시 마이그레이션 강요.

무엇이 Breaking Change?

Breaking	Non-breaking
필드 제거 / 이름 변경	새 필드 추가 (옵션)
필드 타입 변경	새 endpoint 추가
필수 필드 추가	새 enum 값 추가 (옵션 일 때만)
Enum 값 제거	새 query param (옵션)
Endpoint 삭제	새 응답 헤더
응답 status code 변경	rate limit 조정
Auth 방식 변경	에러 메시지 개선 (코드 유지)

4가지 버전 전략

flowchart TD
    Q{버전 표시 방법}
    Q --> URL["URL 버전<br/>/v1/users"]
    Q --> Header["Accept 헤더<br/>application/vnd.api+json;version=2"]
    Q --> Custom["커스텀 헤더<br/>X-API-Version: 2"]
    Q --> Date["날짜 버전<br/>Stripe-Version: 2023-10-16"]

1. URL 버전 (`/v1/...`)

GET /v1/users/42
GET /v2/users/42

장점: 명시적, 브라우저 친화, 캐시 가능, debugging 쉬움. 단점: URL 영구 변경. 자원이 같은데 URL 다름.

가장 흔한 방식. 시작점으로 권장.

2. Accept 헤더

GET /users/42
Accept: application/vnd.example+json;version=2

장점: URL 유지. 단점: 디버깅 어려움 (curl 시 헤더 잊음), 캐싱 복잡.

3. 커스텀 헤더

GET /users/42
X-API-Version: 2

장점: 단순. 단점: 표준 아님.

4. 날짜 기반 (Stripe 방식)

GET /users/42
Stripe-Version: 2023-10-16

Stripe 는 모든 변경에 발표 날짜. 클라이언트는 고정 날짜로 pin. 새 버전으로 명시적 upgrade.

flowchart LR
    A["2023-10-16<br/>(고객 1 pin)"] --> Implementation
    B[2024-04-10] --> Implementation
    C[2025-01-15] --> Implementation
    D["2026-06-25<br/>(최신)"] --> Implementation
    Implementation[서버<br/>다중 버전 동시 지원]

방식	권장 사용처
URL	일반 SaaS API
Accept	RESTful 엄격 + 캐시 인프라 신뢰
커스텀 헤더	내부 / 단순
날짜 (Stripe 식)	결제 / 큰 SDK 생태계 / 세밀한 backward compat

Deprecation Policy

gantt
    title API v1 의 라이프사이클
    dateFormat YYYY-MM-DD
    section Active
    v1 활성 + 지원       :a1, 2024-01-01, 2025-12-31
    section Deprecated
    Deprecation 경고     :crit, d1, 2025-06-01, 2026-06-01
    section Sunset
    Sunset 일시 차단     :s1, 2026-06-01, 2026-12-31
    완전 종료            :milestone, m1, 2026-12-31, 0d

단계	의미	헤더
Active	정상 사용	-
Deprecated	새 사용 자제	`Sunset: <date>`, `Deprecation: <bool>`
Sunset (graceful)	사용 가능, 적극 경고	응답에 경고, 410 응답 일부 endpoint
Removed	410 Gone	-

[!IMPORTANT] Sunset 까지 최소 6-12개월 예고가 정통. 고객사가 단순 라이브러리만 따라잡으면 되도록.

호환성 카테고리

flowchart TD
    Forward[Forward Compatible<br/>옛 클라이언트 → 새 응답 OK]
    Backward[Backward Compatible<br/>새 클라이언트 → 옛 서버 OK]
    Both[양방향 호환]
    Tip1["새 필드 추가 (옵션) → 양방향"]
    Tip2["필드 제거 → 양방향 깨짐"]
    Tip3["응답에 옵션 필드 → forward compatible"]
    Forward --> Tip1
    Forward --> Tip3
    Backward --> Tip1
    Both --> Tip2

클라이언트 라이브러리 정책

정책	효과
Unknown field 무시	forward compatible. 클라이언트 라이브러리의 기본
Unknown field 에러	엄격하지만 호환성 깨짐
Optional 만 처리	가장 안전

Protobuf, JSON 모두 unknown field 무시 가 기본.

흔한 함정

[!WARNING]

버전 없이 시작 = breaking change 강요. 처음부터 v1 박기.

POST 응답에 enum 값 추가 = 클라이언트의 switch case 폭발. unknown case 처리 강제.

deprecation 없이 종료 = 고객 폭동. 최소 6개월 전 알림.

버전 수 폭증 = 5개 동시 지원 = 코드 분기 폭발. 최대 2-3개 동시 지원 권장.

[API Design] GraphQL: 단일 endpoint, N+1, persisted queries

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

GraphQL (Facebook, 2015) 은 클라이언트가 필요한 필드만 명시 하는 query language + 런타임. 단일 endpoint, typed schema, over-fetching / under-fetching 해소.

REST vs GraphQL

항목	REST	GraphQL
Endpoint	여러 개	단일 (`/graphql`)
응답 형태	서버 결정	클라이언트 결정
Over-fetching	흔함	적음
Multiple resources	N 번 요청	1번 쿼리
Type	옵션 (OpenAPI)	필수 (SDL)
캐싱	HTTP cache	응답 단위 (별도)
모니터링	URL 별	쿼리 별 (복잡)
학습 곡선	낮음	중간

Schema (SDL)

type Query {
  user(id: ID!): User
  users(limit: Int = 10, cursor: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

type User {
  id: ID!
  name: String!
  email: String!
  orders(status: OrderStatus): [Order!]!
}

enum OrderStatus { PENDING PAID CANCELLED }

Query / Response

query GetUserWithOrders($id: ID!) {
  user(id: $id) {
    name
    email
    orders(status: PAID) {
      id
      total
      items {
        product { name }
        quantity
      }
    }
  }
}

{
  "data": {
    "user": {
      "name": "koa",
      "email": "koa@x.com",
      "orders": [
        {
          "id": "o_1",
          "total": 19900,
          "items": [{ "product": { "name": "Book" }, "quantity": 2 }]
        }
      ]
    }
  }
}

N+1 문제 (GraphQL 의 함정)

query {
  users {              # 1 query
    name
    orders {           # 각 user 마다 별도 query → N+1!
      total
    }
  }
}

sequenceDiagram
    Client->>GraphQL: query users { orders }
    GraphQL->>DB: SELECT * FROM users      (1)
    DB-->>GraphQL: 100 users
    loop 각 user
        GraphQL->>DB: SELECT * FROM orders WHERE user_id = ?
    end
    Note over GraphQL,DB: 1 + 100 = 101 queries (N+1!)

해결: DataLoader

const orderLoader = new DataLoader(async (userIds) => {
  const orders = await db.orders.find({ user_id: { $in: userIds } });
  return userIds.map(uid => orders.filter(o => o.user_id === uid));
});

const resolvers = {
  User: {
    orders: (user) => orderLoader.load(user.id),
  },
};

DataLoader 가 같은 tick 의 모든 load() 호출을 모아 1 query 로:

sequenceDiagram
    GraphQL->>DataLoader: load(1), load(2), load(3), ...
    Note over DataLoader: 같은 tick 의 호출 모음
    DataLoader->>DB: SELECT * FROM orders WHERE user_id IN (1,2,3,...)
    DB-->>DataLoader: 모든 orders
    DataLoader-->>GraphQL: per-user 결과 분배

[!IMPORTANT] DataLoader 는 GraphQL 의 필수 동반자. 없으면 거의 모든 nested query 가 N+1.

Persisted Queries

매 요청에 전체 쿼리 문자열 보내면 대역폭 + 보안 문제 (악의적 deep nested query 로 DoS).

Persisted Query: 쿼리를 미리 등록 + 해시로 호출.

flowchart LR
    Build[빌드 시] -->|쿼리 → 해시| Reg[(서버에 등록)]
    Client[클라이언트] -->|hash 만 전송| Server
    Server -->|hash → 쿼리 조회| Cache[(query cache)]
    Cache --> Exec[실행]

대역폭 대폭 감소 (긴 쿼리 → 32바이트 해시).
whitelisted query 만 실행 → 보안 강화.
Apollo Persisted Queries / Relay Compiler 가 자동.

Subscription (실시간)

WebSocket 또는 SSE 위에서.

subscription OnNewMessage($roomId: ID!) {
  messageAdded(roomId: $roomId) {
    id
    body
    sender { name }
  }
}

내부적으로 WebSocket (graphql-ws) 또는 SSE.

Federation (단일 graph, 다중 서비스)

여러 서비스가 각자 schema 일부 를 담당. gateway 가 통합 schema.

flowchart TB
    Client -->|query| Gateway[Apollo Router]
    Gateway -->|user subgraph| UserSvc[User Service]
    Gateway -->|order subgraph| OrderSvc[Order Service]
    Gateway -->|payment subgraph| PaySvc[Payment Service]

마이크로서비스 환경의 GraphQL 표준 패턴.

캐싱

GraphQL 은 HTTP cache 가 어려움 (POST + body):

응답 캐시: 같은 query + 변수 → 같은 응답. CDN level 어렵, Apollo Cache / @cacheControl 디렉티브.
DataLoader: per-request 캐싱.
Persisted Query + GET = URL 캐시 가능. CDN 친화.

깊이 / 복잡도 제한 (보안)



const server = new ApolloServer({
  schema,
  validationRules: [
    depthLimit(7),
    createComplexityLimitRule(1000),
  ],
});

[!CAUTION] 클라이언트가 극단적 nested query (user { friends { friends { friends { ... } } } }) 를 보내면 서버 DoS. depth + complexity 제한 필수.

흔한 함정

[!WARNING]

DataLoader 미사용 = 모든 nested 필드 N+1. 처음부터 도입.

Depth limit 없음 = DoS 공격.

모든 필드 nullable = 응답 전체가 null union 형태. 명확한 nullability 명시.

HTTP cache 의 부재 = GraphQL 의 큰 단점. 무거운 쿼리는 외부 cache + persisted query.

[API Design] JSON-RPC vs gRPC vs REST: RPC 패턴 비교

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

RPC (Remote Procedure Call) = 원격 함수 호출 추상화. 세 가지 주요 형태:

JSON-RPC: JSON 위 RPC. 가벼움.
gRPC: Protobuf + HTTP/2.
REST (RPC 스타일): POST /api/getUser 같이 동사 endpoint.

JSON-RPC 2.0 메시지

// 요청
{
  "jsonrpc": "2.0",
  "method": "getUser",
  "params": { "id": 42 },
  "id": 1
}

// 성공 응답
{
  "jsonrpc": "2.0",
  "result": { "id": 42, "name": "koa" },
  "id": 1
}

// 에러 응답
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

// 알림 (응답 없음)
{
  "jsonrpc": "2.0",
  "method": "log",
  "params": ["info", "user logged in"]
}

// Batch (배열)
[
  { "jsonrpc": "2.0", "method": "a", "id": 1 },
  { "jsonrpc": "2.0", "method": "b", "id": 2 }
]

표준 에러 코드	의미
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32000 ~ -32099	server error

세 가지 RPC 비교

항목	JSON-RPC	gRPC	REST (RPC 스타일)
Wire 포맷	JSON	Protobuf	JSON
전송	HTTP/WS/TCP	HTTP/2	HTTP/1.1+
Schema	옵션	필수 (proto)	OpenAPI
Streaming	없음	4 모드	SSE/WS 별도
코드 생성	옵션	자동	OpenAPI
크기 / 속도	JSON 만큼	수배 작고 빠름	JSON
브라우저	직접	grpc-web 필요	직접
Batch	기본 지원	없음	없음

JSON-RPC 의 강점

flowchart LR
    A[가벼운 spec<br/>1 페이지] --> Use1[블록체인 노드<br/>예: Ethereum]
    A --> Use2[IDE / 에디터 ↔ Language Server<br/>예: LSP]
    A --> Use3[VSCode extension API]
    A --> Use4[debugger DAP]

표준	RPC 토대
LSP (Language Server Protocol)	JSON-RPC
DAP (Debug Adapter Protocol)	JSON-RPC
MCP (Model Context Protocol)	JSON-RPC
Ethereum JSON-RPC	JSON-RPC
Bitcoin RPC	JSON-RPC

[!IMPORTANT] JSON-RPC 는 VSCode / LSP / MCP / 블록체인 의 de facto. 복잡도 vs gRPC 의 sweet spot.

언제 어떤 RPC?

flowchart TD
    Q1{브라우저 직접 호출?}
    Q1 -->|예| Q2{내부 API?}
    Q2 -->|"아니오 (외부)"| REST[REST]
    Q2 -->|예| Q3{스트리밍 / typed?}
    Q3 -->|typed 강력 필요| RestOpenAPI[REST + OpenAPI]
    Q3 -->|아니오| REST
    Q1 -->|"아니오 (server-to-server)"| Q4{성능 critical?}
    Q4 -->|예| GRPC[gRPC]
    Q4 -->|아니오| Q5{spec 단순함 중요?}
    Q5 -->|예| JsonRpc[JSON-RPC]
    Q5 -->|아니오| GRPC

JSON-RPC 의 함정

[!WARNING]

method 이름 충돌 = namespace 없음. 큰 시스템에서 접두사 (user.get, order.create) 필요.

HTTP status code 무관 = JSON-RPC 는 항상 200. error 는 body 의 error 객체. 모니터링 도구가 에러 못 잡음.

Batch + notification 의 응답 매핑 = id 기반 매핑이 복잡. 잘못하면 응답이 섞임.

버전 관리 없음 = spec 자체에 버전 없음. 직접 method 이름에 v2 박는 식.

[API Design] OpenAPI / Swagger: 스펙, 코드 생성, contract testing

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

OpenAPI Specification (OAS) 은 REST API 를 기술하는 YAML/JSON 형식. 옛 이름 Swagger. 2017 부터 OpenAPI Initiative (Linux Foundation) 관리.

핵심 가치:

사람이 읽는 문서 (Swagger UI, Redoc)
클라이언트 SDK 자동 생성 (다국어)
서버 stub 생성
contract testing (스펙 ↔ 실제 응답 검증)
mock server

기본 구조

openapi: 3.1.0
info:
  title: Shop API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /items/{id}:
    get:
      summary: Get item by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          description: Not found
components:
  schemas:
    Item:
      type: object
      required: [id, name, price]
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: integer
          minimum: 0

워크플로 (API-first)

flowchart LR
    Design[스펙 작성<br/>openapi.yaml] --> Review[리뷰]
    Review --> Gen[코드 생성]
    Gen --> Server[서버 stub]
    Gen --> Client[클라이언트 SDK]
    Gen --> Mock[Mock server]
    Gen --> Docs[문서 UI]
    Server --> Impl[실제 구현]
    Impl --> Test[contract test]
    Test -->|스펙 위반| Design

OpenAPI 3.1 의 주요 기능

기능	의미
`$ref`	정의 재사용
`components.schemas`	모델 분리
`components.parameters`	공통 파라미터
`components.responses`	공통 응답
`components.securitySchemes`	인증 방식
`oneOf` / `anyOf` / `allOf`	다형성
`discriminator`	type 필드로 분기
`links`	HATEOAS 표현
Webhooks (3.1+)	비동기 콜백

인증 표현

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read:items: Read items
            write:items: Modify items

security:
  - bearerAuth: []

코드 생성 (openapi-generator)

# TypeScript axios 클라이언트
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/client

# Spring Boot 서버 stub
openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./generated/server

지원 언어 수십 가지. 모든 주요 stack 의 클라이언트 SDK 가 자동.

Contract Testing

스펙과 실제 응답 이 일치하는지 검증:

flowchart LR
    Spec[openapi.yaml] -->|검증| Validator
    Server -->|실제 응답| Validator
    Validator -->|불일치| Fail[테스트 실패]
    Validator -->|일치| Pass[테스트 통과]

도구: Schemathesis, Dredd, Prism.

# Schemathesis 로 spec 기반 fuzzing
schemathesis run openapi.yaml --url=https://api.example.com

spec 의 모든 endpoint + 가능한 입력 조합 자동 생성 + 응답 검증.

문서 UI

도구	특징
Swagger UI	표준, try it out 패널
Redoc	세련된 정적 문서, 사이드 nav
Scalar	신예, dark mode + 빠름
Stoplight Elements	임베드 친화

OpenAPI 의 한계

flowchart TD
    Strong[잘 표현되는 것] --> CRUD[CRUD REST]
    Strong --> Webhook[webhook 페이로드]
    Strong --> Type[type-safe 모델]
    Weak[표현 약한 것] --> StateMachine[복잡한 상태 머신]
    Weak --> Realtime["실시간 (WS, SSE)"]
    Weak --> BinaryProto[바이너리 프로토콜]
    Weak --> Workflow[multi-step workflow]

gRPC 는 proto, GraphQL 은 SDL, AsyncAPI 는 비동기 / 이벤트 의 OpenAPI 등가체.

흔한 함정

[!WARNING]

스펙과 실제 응답 의 표류 = contract test 없으면 문서가 거짓말. CI 에 포함.

모든 응답을 200 OK 로 spec = 4xx/5xx 도 명시. 클라이언트 SDK 의 error type 이 정확해짐.

oneOf 의 없는 discriminator = 클라이언트가 어떤 타입인지 구분 못함. 항상 discriminator 명시.

너무 늦게 spec 작성 = 코드부터 작성 후 spec 은 retrospective spec 으로 문서 정확도 떨어짐. API-first 가 정통.

[API Design] REST API: 원칙, 자원 모델링, HATEOAS, 버전 관리

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

REST (Representational State Transfer) 는 Roy Fielding 의 2000년 박사논문에서 정립된 분산 시스템 아키텍처 스타일. HTTP 의 자원 / 표현 / 상태 전이 를 자연스럽게 활용.

[!IMPORTANT] “REST” 라는 단어는 대부분 실무에서 HTTP+JSON CRUD 를 의미. Fielding 의 순수 REST (HATEOAS 포함) 는 드물게 적용. 이 페이지는 실무 REST 와 진짜 REST 둘 다 정리.

Richardson Maturity Model (REST 의 4 단계)

flowchart TB
    L0[Level 0: 단일 endpoint<br/>POST /api 로 모든 작업] --> L1[Level 1: 자원 분리<br/>GET /users, /orders]
    L1 --> L2[Level 2: HTTP method + status<br/>GET/POST/PUT/DELETE]
    L2 --> L3[Level 3: HATEOAS<br/>응답에 next action 링크]

실무 대부분은 Level 2 에 머문다. Level 3 은 Stripe, GitHub API 의 일부 정도.

자원 모델링

좋은 패턴	나쁜 패턴
`GET /users/42`	`GET /getUser?id=42`
`POST /users` (생성)	`POST /createUser`
`DELETE /users/42`	`POST /deleteUser`
`GET /users/42/orders`	`GET /userOrders?uid=42`
`POST /users/42/email/verify` (action)	`GET /verifyUserEmail?uid=42`

규칙:

명사로 자원 표현 (users, orders)
복수형 권장 (users not user)
상태 변경 은 HTTP method 로
체이닝 자원으로 관계 표현 (/users/42/orders/9)
비-CRUD action 은 복합 명사 (/orders/9/cancel, /payments/p_123/refund)

HTTP Method 매핑

Method	멱등	안전	사용
GET	O	O	조회
HEAD	O	O	헤더만
POST	X	X	생성, 비-멱등 action
PUT	O	X	전체 교체
PATCH	X (대개)	X	부분 갱신
DELETE	O	X	삭제

[!NOTE] PUT 은 idempotent. 두 번 호출 = 한 번 호출 결과 같음. POST 는 매번 새 자원 생성.

Status Code 패턴

코드	사용
200	성공 (GET, PUT, PATCH)
201	생성 (POST). `Location` 헤더로 새 자원 URL
202	비동기 접수
204	본문 없음 성공 (DELETE)
400	입력 형식 / 필수 누락
401	인증 필요
403	인증 됐지만 권한 없음
404	자원 없음
409	충돌 (중복, 동시성)
422	형식은 OK, 의미 검증 실패
429	rate limit 초과

API 버전 관리

flowchart LR
    Q{버전 표시 방법}
    Q --> URL["URL: /v1/users<br/>/v2/users"]
    Q --> Header["헤더: Accept: application/vnd.api+json;v=2"]
    Q --> Query["Query: /users?api-version=2"]

방식	장점	단점
URL (`/v1/`)	명시적, 캐싱 친화	URL 영구 변경
Accept 헤더	URL 깔끔	디버깅 / 캐시 어려움
Query	단순	URL 변형

Stripe 는 날짜 기반 버전 (Stripe-Version: 2023-10-16). 가장 세밀하고 안전한 호환성.

페이지네이션

flowchart LR
    A[Offset/Limit<br/>?offset=20&limit=10] --> B[페이지 N 빠른 점프 가능]
    C[Cursor<br/>?cursor=abc123] --> D[연속 스트림, 정확]
    E[Page/Size<br/>?page=3&size=10] --> F[옛 패턴]

방식	장점	단점
Offset	임의 점프	큰 offset 시 O(N) DB query
Cursor	빠름, 정확	임의 점프 불가
Keyset	offset + cursor 의 장점	구현 복잡

[!TIP] 대량 데이터 + 무한 스크롤 = 거의 항상 cursor 기반. Stripe, GitHub, Twitter API 모두.

응답 포맷 (envelope)

{
  "data": [...],
  "meta": {
    "total": 1024,
    "page": 1,
    "per_page": 20
  },
  "links": {
    "self": "...",
    "next": "...",
    "prev": null
  }
}

또는 납작 (JSON:API 스펙):

{
  "data": [{ "id": "1", "type": "users", "attributes": { ... } }]
}

[!CAUTION] envelope 의 너무 깊은 nesting 은 클라이언트 코드 복잡. flat + 표준 (RFC 7807 problem details for errors) 권장.

에러 응답 (RFC 7807)

{
  "type": "https://example.com/probs/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Email is required",
  "instance": "/requests/12345",
  "errors": [
    { "field": "email", "code": "REQUIRED" }
  ]
}

HATEOAS

응답에 다음 가능 action 의 링크 포함:

{
  "id": "o_123",
  "status": "pending",
  "links": {
    "self": "/orders/o_123",
    "cancel": "/orders/o_123/cancel",
    "pay": "/orders/o_123/pay"
  }
}

[!NOTE] 클라이언트가 URL 을 미리 알 필요 없이 응답의 링크만 따라 가는 진짜 REST. 실무에서는 드물지만 GitHub API 가 좋은 예.

흔한 함정

[!WARNING]

/users/getById 같은 동사 URL = REST 의 자원 사상 위반.

모든 변경에 PUT = PATCH 가 적절한 부분 갱신에도 PUT 사용 → race condition.

POST 의 비-멱등 위험 = 네트워크 재시도 시 중복 생성. Idempotency-Key 헤더로 해결.

버전 없이 시작 = breaking change 시 모든 클라이언트 동시 마이그레이션 강요.

김신건의 로그 - 위키 / api-design

[API Design] API Versioning: URL / Header / Date 비교

정의

무엇이 Breaking Change?

4가지 버전 전략

1. URL 버전 (/v1/...)

2. Accept 헤더

3. 커스텀 헤더

4. 날짜 기반 (Stripe 방식)

Deprecation Policy

호환성 카테고리

클라이언트 라이브러리 정책

흔한 함정

관련 위키

[API Design] GraphQL: 단일 endpoint, N+1, persisted queries

정의

REST vs GraphQL

Schema (SDL)

Query / Response

N+1 문제 (GraphQL 의 함정)

해결: DataLoader

Persisted Queries

Subscription (실시간)

Federation (단일 graph, 다중 서비스)

캐싱

깊이 / 복잡도 제한 (보안)

흔한 함정

관련 위키

[API Design] JSON-RPC vs gRPC vs REST: RPC 패턴 비교

정의

JSON-RPC 2.0 메시지

세 가지 RPC 비교

JSON-RPC 의 강점

언제 어떤 RPC?

JSON-RPC 의 함정

관련 위키

[API Design] OpenAPI / Swagger: 스펙, 코드 생성, contract testing

정의

기본 구조

워크플로 (API-first)

OpenAPI 3.1 의 주요 기능

인증 표현

코드 생성 (openapi-generator)

Contract Testing

문서 UI

OpenAPI 의 한계

흔한 함정

관련 위키

[API Design] REST API: 원칙, 자원 모델링, HATEOAS, 버전 관리

정의

Richardson Maturity Model (REST 의 4 단계)

자원 모델링

HTTP Method 매핑

Status Code 패턴

API 버전 관리

페이지네이션

응답 포맷 (envelope)

에러 응답 (RFC 7807)

HATEOAS

흔한 함정

관련 위키

1. URL 버전 (`/v1/...`)