# API 合約設計 (API Contract Design) 知識合約指南

## 概述
`api-contract-design` 是知識合約，不是 workflow 技能。用來定義 API 合約的設計原則，包含請求/回應結構、狀態碼、分頁機制、認證邊界與冪等性行為。供 `design-architecture` 在定義 API 時參考。

## 核心原則
- API 是生產者與消費者之間的合約，穩定性與清晰度至關重要
- 每個端點必須服務至少一個 PRD 功能需求
- 合約必須明確、完整且無歧義
- 破壞性變更必須避免；必須規劃版本管理

## 設計重點
- REST API：端點定義、請求結構、回應結構、狀態碼、分頁、過濾
- 非 REST API：GraphQL schema、gRPC service 定義、WebSocket 訊息格式
- 錯誤回應格式：一致的錯誤碼、機器可讀與人類可讀的訊息
- 版本策略：URL path versioning 與 header versioning 的適用場景

## 知識合約職責
- 提供 API 設計的理論指引
- 不直接產生 API 規格（由 `generate_openapi_spec` 負責格式）
- 與 `generate_openapi_spec` 搭配使用：前者提供原則，後者提供格式

## 不應做的事
- 不產生 API 規格檔案
- 不替特定端點命名或定義結構（那是 `design-architecture` 的職責）
- 不做最終技術選型