api-design-assistant
/api-design-assistant
引導 API 設計,遵循 REST、GraphQL 與 gRPC 最佳實踐。 Use when: 設計 API、審查端點、API 版本策略決策。 Not for: 驗證運行中的 API 是否符合消費端期待——請用 /contract-test;API 背後的 schema 設計——請用 /database。 Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計, 端點, 版本策略.
- Author
- AsiaOstrich ↗
- Repository
- universal-dev-standards ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
引導 API 設計,遵循 REST、GraphQL 與 gRPC 最佳實踐。 Use when: 設計 API、審查端點、API 版本策略決策。 Not for: 驗證運行中的 API 是否符合消費端期待——請用 /contract-test;API 背後的 schema 設計——請用 /database。 Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計, 端點, 版本策略.
Arguments
/api-design-assistant [API 端點或模組]
Original author description
引導 API 設計,遵循 REST、GraphQL 與 gRPC 最佳實踐。 Use when: 設計 API、審查端點、API 版本策略決策。 Not for: 驗證運行中的 API 是否符合消費端期待——請用 /contract-test;API 背後的 schema 設計——請用 /database。 Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計, 端點, 版本策略.
How it works
- 快速參考 — REST 慣例
- 設計工作流程
- 版本策略
- 使用方式
- 下一步引導
- 參考
- 版本歷史
- 授權
SKILL.md preview
---
name: api-design-assistant
source: ../../../../skills/api-design-assistant/SKILL.md
source_version: 1.0.0
translation_version: 1.1.0
last_synced: 2026-10-11
source_hash: 11f1ca291530
status: current
scope: universal
description: |
引導 API 設計,遵循 REST、GraphQL 與 gRPC 最佳實踐。
Use when: 設計 API、審查端點、API 版本策略決策。
Not for: 驗證運行中的 API 是否符合消費端期待——請用 /contract-test;API 背後的 schema 設計——請用 /database。
Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計, 端點, 版本策略.
allowed-tools: Read, Grep, Glob
argument-hint: "[API 端點或模組]"
---
# API 設計助手
> **語言**: [English](../../../../skills/api-design-assistant/SKILL.md) | 繁體中文
引導 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`
## 參考
- 核心規範:[api-design-standards.md](../../../../core/api-design-standards.md)
## 版本歷史
| 版本 | 日期 | 變更說明 |
|------|------|----------|
| 1.0.0 | 2026-03-23 | 初始版本 |
## 授權
CC BY 4.0 — 文件內容
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · AsiaOstrich/universal-dev-standards | 95 | MIT |
| ArabelaTso/Skills-4-SE | 100 | Apache-2.0 |
| AsiaOstrich/universal-dev-standards | 84 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version b284de9c5aad (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90api-design
引導 API 設計,遵循 REST、GraphQL 與 gRPC 最佳實踐。 Use when: 設計 API、審查端點、API 版本策略決策。 Not for: 驗證運行中的 API 是否符合消費端期待——請用 /contract-test;API 背後的 schema 設計——請用 /database。 Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計, 端點, 版本策略. - 90api-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,… - 100api-design
REST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming. - 100api-design
Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap. - 90proof-api
Build API test suites — endpoint testing, contract testing, load testing for REST/GraphQL/gRPC APIs. Use when asked to "test this API", "API tests", "endpoint testing", "contract tests", or "load test". - 90api-design
API design patterns: REST naming/pagination/errors, GraphQL schema design, gRPC streaming, versioning strategies, idempotency keys, rate limiting. Use when designing APIs.