asiaostrich/api-design

API Design Assistant | API 設計助手

Guide API design following REST, GraphQL, and gRPC best practices.

引導 API 設計，遵循 REST、GraphQL 和 gRPC 最佳實踐。

Quick Reference — REST Conventions | 快速參考

HTTP Methods | HTTP 方法

| Method | Purpose | Idempotent | 用途 | |--------|---------|------------|------| | GET | Read resource | Yes | 讀取資源 | | POST | Create resource | No | 建立資源 | | PUT | Replace resource | Yes | 替換資源 | | PATCH | Partial update | No | 部分更新 | | DELETE | Remove resource | Yes | 刪除資源 |

Status Codes | 狀態碼

| Code | Meaning | 說明 | |------|---------|------| | 200 | OK | 成功 | | 201 | Created | 已建立 | | 204 | No Content | 無內容（刪除成功） | | 400 | Bad Request | 請求格式錯誤 | | 401 | Unauthorized | 未認證 | | 403 | Forbidden | 無權限 | | 404 | Not Found | 資源不存在 | | 409 | Conflict | 資源衝突 | | 422 | Unprocessable Entity | 驗證失敗 | | 429 | Too Many Requests | 請求過多（限流） | | 500 | Internal Server Error | 伺服器內部錯誤 |

URL Naming | URL 命名規則

| Pattern | Example | 說明 | |---------|---------|------| | Collection | /users | 資源集合 | | Singleton | /users/{id} | 單一資源 | | Sub-resource | /users/{id}/orders | 子資源 | | Action | /users/{id}/activate | 動作（僅限 POST） |

Design Workflow | 設計工作流程

DEFINE ──► DESIGN ──► VALIDATE ──► DOCUMENT

1. Define — Identify Requirements | 定義需求

Clarify consumers, use cases, data models, and non-functional requirements.

釐清使用者、使用情境、資料模型和非功能性需求。

2. Design — Structure Endpoints | 設計端點

Apply RESTful conventions, define request/response schemas, plan versioning.

套用 RESTful 慣例、定義請求/回應 Schema、規劃版本策略。

3. Validate — Review Consistency | 驗證一致性

Check naming consistency, error format uniformity, pagination patterns.

檢查命名一致性、錯誤格式統一、分頁模式。

4. Document — Generate Specs | 產生文件

Produce OpenAPI/Swagger specs or GraphQL schema documentation.

產出 OpenAPI/Swagger 規格或 GraphQL Schema 文件。

Versioning Strategy | 版本策略

| Strategy | Example | Pros | 優點 | |----------|---------|------|------| | URL Path | /v1/users | Simple, explicit | 簡單、明確 | | Header | Accept: application/vnd.api+json;v=1 | Clean URLs | URL 乾淨 | | Query | /users?version=1 | Easy to test | 容易測試 |

Usage | 使用方式

/api-design              - Interactive API design guide | 互動式 API 設計引導
/api-design /users       - Review specific endpoint design | 審查特定端點設計
/api-design --graphql    - GraphQL schema design guide | GraphQL Schema 設計引導

Next Steps Guidance | 下一步引導

After /api-design completes, the AI assistant should suggest:

API 設計完成。建議下一步 / API design complete. Suggested next steps:

• 執行 /sdd 建立正式規格文件 ⭐ Recommended / 推薦 — Create formal specification
• 執行 /testing 規劃 API 測試策略 — Plan API testing strategy
• 執行 /docs 產生 API 文件 — Generate API documentation
• 審查安全性 → 執行 /security — Review security → Run /security

Reference | 參考

• Core standard: api-design-standards.md

Version History | 版本歷史

| Version | Date | Changes | 變更說明 | |---------|------|---------|----------| | 1.0.0 | 2026-03-23 | Initial release | 初始版本 |

License | 授權

CC BY 4.0 — Documentation content