api-design
Guide API design following REST, GraphQL, and gRPC best practices. Use when: designing APIs, reviewing endpoints, API versioning decisions. Not for: verifying a running API against its consumers — use /contract-test; schema design behind the API — use /database. Keywords: API, REST, GraphQL, gRPC, endpoint, versioning.
Source facts
- Repository
- AsiaOstrich/universal-dev-standards
- Last source activity
- August 17, 2026 at 06:20
- Detected SKILL.md language
- Mixed languages
- Stars
- 80
- Forks
- 14
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview- name
- api-design
- scope
- universal
- description
- Guide API design following REST, GraphQL, and gRPC best practices. Use when: designing APIs, reviewing endpoints, API versioning decisions. Not for: verifying a running API against its consumers — use /contract-test; schema design behind the API — use /database. Keywords: API, REST, GraphQL, gRPC, endpoint, versioning.
- allowed-tools
- Read, Grep, Glob
- argument-hint
- [API endpoint or module | API 端點或模組]
# 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](../../core/api-design-standards.md)
## Version History | 版本歷史
| Version | Date | Changes | 變更說明 |
|---------|------|---------|----------|
| 1.0.0 | 2026-03-23 | Initial release | 初始版本 |
## License | 授權
CC BY 4.0 — Documentation content
View on GitHub