Skip to content
Skills Library
Programming · Planning

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, 介面設計, 端點, 版本策略.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. 快速參考 — REST 慣例
  2. 設計工作流程
  3. 版本策略
  4. 使用方式
  5. 下一步引導
  6. 參考
  7. 版本歷史
  8. 授權
Original SKILL.md headings · 102 lines, 328 words
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

RepositoryScoreLicence
This page · AsiaOstrich/universal-dev-standards95MIT
ArabelaTso/Skills-4-SE100Apache-2.0
AsiaOstrich/universal-dev-standards84MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.