AsiaOstrich API 設計助手
語言: English | 繁體中文
引導 API 設計，遵循 REST、GraphQL 和 gRPC 最佳實踐。
快速參考 — REST 慣例
HTTP 方法
| 方法 | 用途 | 冪等性 |
|---|---|---|
| GET | 讀取資源 | 是 |
| POST | 建立資源 | 否 |
| PUT | 替換資源 | 是 |
| PATCH | 部分更新 | 否 |
| DELETE | 刪除資源 | 是 |
狀態碼
| 代碼 | 說明 |
|---|---|
| 200 | 成功 |
| 201 | 已建立 |
| 204 | 無內容（刪除成功） |
| 400 | 請求格式錯誤 |
| 401 | 未認證 |
| 403 | 無權限 |
| 404 | 資源不存在 |
| 409 | 資源衝突 |
| 422 | 驗證失敗 |
| 429 | 請求過多（限流） |
| 500 | 伺服器內部錯誤 |
URL 命名規則
| 模式 | 範例 | 說明 |
|---|---|---|
| 集合 | /users |
資源集合 |
| 單一資源 | /users/{id} |
單一資源 |
| 子資源 | /users/{id}/orders |
子資源 |
| 動作 | /users/{id}/activate |
動作（僅限 POST） |
設計工作流程
DEFINE ──► DESIGN ──► VALIDATE ──► DOCUMENT
1. Define — 定義需求
釐清使用者、使用情境、資料模型和非功能性需求。
2. Design — 設計端點
套用 RESTful 慣例、定義請求/回應 Schema、規劃版本策略。
3. Validate — 驗證一致性
檢查命名一致性、錯誤格式統一、分頁模式。
4. Document — 產生文件
產出 OpenAPI/Swagger 規格或 GraphQL Schema 文件。
版本策略
| 策略 | 範例 | 優點 |
|---|---|---|
| URL 路徑 | /v1/users |
簡單、明確 |
| Header | Accept: application/vnd.api+json;v=1 |
URL 乾淨 |
| Query | /users?version=1 |
容易測試 |
使用方式
/api-design- 互動式 API 設計引導/api-design /users- 審查特定端點設計/api-design --graphql- GraphQL Schema 設計引導
下一步引導
/api-design 完成後，AI 助手應建議：
API 設計完成。建議下一步：
- 執行
/sdd建立正式規格文件- 執行
/testing規劃 API 測試策略- 執行
/docs產生 API 文件- 審查安全性 → 執行
/security