Terry Yao's Blog

ROADMAP

ROADMAP

閱讀時間約 7 分鐘

B09 · API 設計 詳細 ROADMAP

計畫文件，不會被 Quartz 渲染。 回主 roadmap → backend/ROADMAP.md

章節目標

API 是後端對外的面孔。設計好，前端 / 第三方 / 未來的自己都感謝；設計爛，每一個版本都要道歉。本章聚焦：REST / GraphQL / gRPC 三種風格深入、API 版本管理、錯誤碼設計、冪等性、Rate Limit、文件自動化、OpenAPI 生態。

🌱 基本介紹

#主題SlugStage大綱
01API 設計是什麼01-what-is-api-design🌱API 作為契約；backward / forward compatibility；Richardson Maturity Model

❓ 為什麼需要

#主題SlugStage大綱
02為什麼糟糕的 API 會毀掉你的後端02-why-api-design-matters🌱每個 breaking change 都要通知前端、APP、第三方；版本管理失控；文件跟實作不一致
03為什麼不是 GraphQL / gRPC 取代 REST03-why-rest-still-wins🌱可被 curl / browser debug、CDN / cache 原生支援、人類可讀、開發者心智負擔最低
04為什麼要強制 OpenAPI04-why-openapi-mandatory🌱SDK 自動生成、跟前端 / APP 的 type-safe contract、mock server、文件自動化

🕰️ 演進

#主題SlugStage大綱
05API 設計演進史05-api-design-evolution🌱SOAP → REST → JSON-RPC → GraphQL（2015）→ gRPC → tRPC → REST + OpenAPI 復興（2020+）
06OpenAPI 演進06-openapi-evolution🌱Swagger 1.2 → OpenAPI 2.0（Swagger）→ 3.0 → 3.1（JSON Schema 對齊）

🧠 知識型

F09-A REST 深入

#主題SlugStage大綱
07RESTful 基礎⛔️ fundamentals/restful-api🌿跨系列
08Richardson Maturity Model08-richardson-maturity-model🌱Level 0 → 1 → 2 → 3（HATEOAS）；大多數 API 停在 Level 2
09RESTful URL 設計09-restful-url-design🌱resource naming、nested resources、filter / sort / pagination 的 URL 風格
10HTTP method 語意10-http-method-semantics🌱GET / POST / PUT / PATCH / DELETE；PUT vs PATCH（idempotent vs partial update）
11Status Code 設計11-status-code-design🌱2xx / 3xx / 4xx / 5xx；為什麼 200 回 {"error": "..."} 是 anti-pattern

F09-B GraphQL

#主題SlugStage大綱
12GraphQL 後端視角12-graphql-backend-view🌱Schema / Resolver / DataLoader；跟 REST 的 trade-off
13N+1 問題 / DataLoader13-graphql-n-plus-1🌱為什麼 GraphQL 天生 N+1；DataLoader batching / caching 對策
14GraphQL Subscriptions14-graphql-subscriptions🌱WebSocket / SSE 實作、scaling 挑戰

F09-C gRPC

#主題SlugStage大綱
15gRPC 服務設計15-grpc-service-design🌱Protobuf service definition、4 種 streaming 的實戰場景
16gRPC 錯誤處理16-grpc-error-handling🌱Status code、error detail、跟 REST status 對齊
17Protobuf schema 演進17-protobuf-schema-evolution🌱field number 不能重用、reserved、backward compat 策略

F09-D API Versioning

#主題SlugStage大綱
18API Versioning 策略18-api-versioning-strategies🌱URL path（/v1/）vs header（Accept: application/vnd.api.v1+json）vs query param；各自優缺
19Deprecation 流程19-api-deprecation🌱Sunset header、文件通知、grace period、強制下線時機

F09-E 可靠性

#主題SlugStage大綱
20Idempotency（冪等性）20-idempotency🌱Idempotency-Key header、金流 POST 重複請求、server-side 怎麼存 key
21Rate Limiting21-rate-limiting🌱Fixed window / Sliding window / Token Bucket / Leaky Bucket；Kong / CloudFlare / Redis 實作
22Retry 策略（伺服器視角）22-server-retry-strategy🌱哪些 endpoint 該可重試、哪些必須冪等；Retry-After header
23Circuit Breaker23-circuit-breaker🌱保護下游服務、跟微服務通訊整合、Hystrix / Resilience4j

F09-F 錯誤與回傳格式

#主題SlugStage大綱
24錯誤碼設計24-error-code-design🌱機器可讀 vs 人類可讀、錯誤碼結構（domain:action:reason）、i18n
25Problem Details（RFC 7807）25-rfc-7807-problem-details🌱標準化錯誤格式、type / title / detail / instance；為什麼值得採用
26Envelope pattern26-envelope-pattern🌱{data: ..., meta: ..., error: null} vs 純 payload；各自 trade-off

F09-G 文件與契約

#主題SlugStage大綱
27OpenAPI / Swagger⛔️ fundamentals/swagger🌿跨系列
28API 設計完整指南⛔️ system-design/03-api-design🌿跨系列
29Proto Planning⛔️ system-design/05-proto-planning🌿跨系列
30OpenAPI → 跨語言 SDK 自動生成30-openapi-codegen-sdk🌱openapi-generator、Swagger Codegen、團隊 workflow

F09-H 特殊協議

#主題SlugStage大綱
31WebSocket 實戰⛔️ infra/23-websocket / micro-service/26-websocket-sse🌿跨系列
32Server-Sent Events（後端實作）32-sse-backend-impl🌱FastAPI / Express / Spring 各語言 SSE 實作；AI chat streaming 案例
33Webhook 設計33-webhook-design🌱Payload 設計、重試、HMAC 簽名、idempotency；參考 Stripe / GitHub

F09-I API 文件化生態與 Governance

API 文件不只 Swagger UI。2026 的後端團隊要有完整的文件化 discipline。

#主題SlugStage大綱
34OpenAPI 工具鏈全景34-openapi-toolchain🌱Swagger UI / Redoc / Stoplight / Scalar 對比；spec first vs code first；auto-generated 的來源（FastAPI / springdoc / Swashbuckle）
35AsyncAPI：事件驅動文件標準35-asyncapi🌱OpenAPI 不涵蓋 event / queue；AsyncAPI 3.0 的角色；跟 RabbitMQ / Kafka schema 整合
36API Governance 實作36-api-governance🌱Spectral lint / Azure API Center / SwaggerHub；CI 自動檢查；team 共用 style guide
37Spec Linting（Spectral）實戰37-spectral-linting🌱自訂 rule、CI 整合、常用 rule 範例（naming / versioning / security）
38API Deprecation Policy38-api-deprecation-policy🌱Sunset header / 通知流程 / grace period；跟 consumer 協作機制
39API Portal 對外設計39-api-portal🌱Public-facing developer portal；SDK 自動生成 + 文件 + changelog + sandbox；Stripe / Twilio 模板
40ADR（Architecture Decision Record）工具鏈40-adr-toolchain🌱MADR / Log4brains / adr-tools；git-based ADR；跟 B08 #24 連動但聚焦工具
41Runbook 系統41-runbook-system🌱On-call 必要文件；跟 alert 綁定；執行腳本化（ChatOps）；template 設計
42Architecture Diagram-as-Code42-diagram-as-code🌱C4 model / D2 / Mermaid / PlantUML / Structurizr；避免 PowerPoint rot；版本控制
43Internal Docs Stack43-internal-docs-stack🌱Docusaurus / MkDocs / Starlight / Nextra / Backstage TechDocs；選型決策；跟 monorepo 整合

🔧 小實作注意事項

#主題SlugStage大綱
44從 OpenAPI spec 起手設計 API44-openapi-first-design🌱design → spec → impl / SDK / mock；跟 code-first 比較
45API 契約測試（Pact）45-pact-contract-testing🌱consumer-driven contract、CI 整合
46用 Postman / Bruno / HTTPie 管理 API collection46-api-collection-tools🌱團隊共用、環境變數、CI 整合

💣 Anti-pattern

#主題SlugStage大綱
47API 設計 Anti-patterns47-api-design-antipatterns🌱GET 打 action（GET /deleteUser）、200 回 error body、URL 裡塞動詞、status code 隨便選、沒版本硬改 schema、錯誤訊息只給使用者不給 developer、pagination 用 offset 不用 cursor（大資料集爆）

🧰 對應檢查工具

#主題SlugStage大綱
48API 品質工具48-api-tooling🌱Spectral（OpenAPI lint）、Postman / Bruno、Schemathesis / Dredd（contract）、Stoplight、Redocly

📎 補充

#主題SlugStage大綱
S01JSON:API 標準s01-jsonapi-spec🌱統一的 JSON response format、relationships、sparse fieldset
S02HATEOAS 死了嗎s02-hateoas-dead🌱Roy Fielding 原旨、為什麼 99% API 不做、什麼場景還有價值
S03好的 API 設計怎麼看⛔️ standards/03-good-api-design🌿跨系列
S04Billing / Metering Backends04-billing-metering🌱SaaS usage metering 設計、API 使用量計費、invoice 生成、按 user / tenant 分帳；Stripe Metered Billing / OpenMeter pattern
S05金流整合s05-payment-integration🌱Stripe / 綠界 / TapPay；webhook 重試 / idempotency；對帳流程；PCI-DSS 基本認知

章節進度統計

  • 知識主題：38 + 3 補充 = 41 項
  • 🌿 growing：6（跨系列）
  • 🌱 seed：35

跨系列連結

  • → fundamentals/restful-api、fundamentals/swagger
  • → system-design/03-api-design、system-design/05-proto-planning
  • → backend/network/ B02（API 協議層）
  • → backend/auth/ B10（API 認證）
  • → backend/framework/ B06（framework 的路由 / validation / error）
  • → infra/21-api-gateway、infra/23-websocket
  • → standards/03-good-api-design

關係圖譜

反向連結

  • ROADMAP

    Walkthroughs 詳細 ROADMAP 計畫文件，不會被 Quartz 渲染（無 frontmatter）。 公...