Skip to content
Skills Library
Programming · Planning

api-design

/api-design

引導 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
08.11.2026

Assessment and security

90/ 100Class: good
Format20 / 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
2
Deprecation

No signals detected. Repository changed on 08.11.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 [API endpoint or module | 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
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 endpoint or module | API 端點或模組]"
---

# API 設計助手

> **語言**: [English](https://github.com/AsiaOstrich/universal-dev-standards/blob/main/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](https://github.com/AsiaOstrich/universal-dev-standards/blob/main/core/api-design-standards.md)

## 版本歷史

| 版本 | 日期 | 變更說明 |
|------|------|----------|
| 1.0.0 | 2026-03-23 | 初始版本 |

## 授權

CC BY 4.0 — 文件內容

Versions

RepositoryScoreLicence
This page · AsiaOstrich/universal-dev-standards90MIT
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

Database snapshot: 13.11.2026 · package version ac32232ac054 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95api-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, 介面設計, 端點, 版本策略.
  • 84api-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, 接口设计, 端点, 版本策略.
  • 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".
  • 100api
    Use for API design — REST/GraphQL/gRPC. Versioning, error shape, auth, idempotency, pagination, rate limits. Output is a spec + scaffold.
  • 100api-design-ops
    API design patterns for REST, gRPC, and GraphQL. Use for: api design, REST, gRPC, GraphQL, protobuf, schema design, api versioning, pagination, rate limiting, error format, OpenAPI, API authentication, JWT, OAuth2, API gateway, webhook, idempotency.
  • 100design-api
    Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract".

Feedback and reports

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