asiaostrich/api-design
.gemini/skills/api-design-assistant/SKILL.md
[UDS] 引導 API 設計，遵循 REST、GraphQL 和 gRPC 最佳實踐
$ install --global
skillsauthnpx skillsauth add asiaostrich/universal-dev-standards api-designInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 3, 2026, 10:49 AM22.8s1 file scanned
SKILL.md
- source:
- ../../../../skills/api-design-assistant/SKILL.md
- source_version:
- 1.0.0
- translation_version:
- 1.0.0
- last_synced:
- 2026-03-23
- status:
- current
- description:
- [UDS] 引導 API 設計，遵循 REST、GraphQL 和 gRPC 最佳實踐
- name:
- api-design
- allowed-tools:
- Read, Grep, Glob
- scope:
- universal
- argument-hint:
- [API endpoint or module | API 端點或模組]
API 設計助手
語言: English | 繁體中文
引導 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
Related Skills
asiaostrich/sweep
development
VerifiedTrustedCommunity
[UDS] 扫描代码库的调试残留与代码质量问题；可自动修正安全模式。 Use when: before committing, during PR review, or periodic codebase cleanup. Keywords: sweep, debug cleanup, console.log, debugger, TODO, ts-any, code quality, 扫描, 清理.
69SKILL.mdUpdated Jun 4, 2026
asiaostrich/spec-derive
tools
VerifiedTrustedCommunity
[UDS] 从规格衍生 BDD 场景、TDD 骨架或 ATDD 表格
69SKILL.mdUpdated Jun 4, 2026
asiaostrich/skill-builder
development
VerifiedTrustedCommunity
[UDS] 识别重复流程并以正确的开发深度构建 Skill
69SKILL.mdUpdated Jun 4, 2026
asiaostrich/push
tools
VerifiedTrustedCommunity
[UDS] AI 辅助 git push 安全层：质量门禁 + 协作护栏。 Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches. Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保护分支, 质量门禁.
69SKILL.mdUpdated Jun 4, 2026