Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

api-design

/api-design

Prowadzi projektowanie API zgodnie z dobrymi praktykami REST, GraphQL i gRPC: endpointy, przeglądy i strategię wersjonowania.

Licencja
MIT
Ostatnia zmiana repozytorium
08.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść30 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 08.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi projektowanie API zgodnie z dobrymi praktykami REST, GraphQL i gRPC: endpointy, przeglądy i strategię wersjonowania.

Argumenty

/api-design [API endpoint or module | API 端點或模組]
Oryginalny opis (EN)

引導 API 設計,遵循 REST、GraphQL 與 gRPC 最佳實踐。 Use when: 設計 API、審查端點、API 版本策略決策。 Not for: 驗證運行中的 API 是否符合消費端期待——請用 /contract-test;API 背後的 schema 設計——請用 /database。 Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計, 端點, 版本策略.

Jak działa

  1. 快速參考 — REST 慣例
  2. 設計工作流程
  3. 版本策略
  4. 使用方式
  5. 下一步引導
  6. 參考
  7. 版本歷史
  8. 授權
Sekcje z nagłówków SKILL.md, w oryginale · 102 linii, 328 słów
Podgląd SKILL.md
---
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 — 文件內容

Wersje

RepozytoriumWynikLicencja
Ta strona · 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

Migawka bazy z 13.11.2026 · wersja paczki ac32232ac054 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95api-design-assistant
    Prowadzi projektowanie API zgodnie z dobrymi praktykami REST, GraphQL i gRPC, a także przy decyzjach o wersjonowaniu.
  • 84api-design-assistant
    Prowadzi projektowanie API według dobrych praktyk REST, GraphQL i gRPC, także przy wersjonowaniu i przeglądzie endpointów.
  • 90proof-api
    Buduje zestawy testów API: testy endpointów, kontraktowe i obciążeniowe dla REST, GraphQL i gRPC.
  • 100api
    Prowadzi projektowanie API REST, GraphQL i gRPC: wersjonowanie, kształt błędów, uwierzytelnianie, idempotencja, paginacja i limity, z wynikiem w postaci specyfikacji i szkieletu.
  • 100api-design-ops
    Podaje wzorce projektowania API dla REST, gRPC i GraphQL: protobuf, schematy, wersjonowanie, paginacja, limity, format błędów, OpenAPI, JWT, OAuth2 i bramki.
  • 100design-api
    Projektuje API REST i GraphQL: nazewnictwo, wersjonowanie, kształt błędów i uwierzytelnianie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.