AgentSkillsCN

API 設計技能

REST API 与 GraphQL 设计指南

SKILL.md
--- frontmatter
name: API 設計技能
description: REST API 和 GraphQL 設計指南

🔌 API 設計技能

REST API

端點設計

動作方法路徑說明
列表GET/users取得列表
建立POST/users建立資源
取得GET/users/:id取得單個
更新PUT/users/:id完整更新
部分更新PATCH/users/:id部分更新
刪除DELETE/users/:id刪除

巢狀資源

code
GET /users/:id/posts         # 用戶的文章
POST /users/:id/posts        # 為用戶建立文章
GET /posts/:id/comments      # 文章的評論

回應格式

成功回應

json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "John"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

列表回應

json
{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  }
}

錯誤回應

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "驗證失敗",
    "details": {
      "email": "格式不正確"
    }
  }
}

HTTP 狀態碼

說明使用時機
200OK成功
201Created建立成功
204No Content刪除成功
400Bad Request請求錯誤
401Unauthorized未認證
403Forbidden無權限
404Not Found找不到
422Unprocessable驗證失敗
500Server Error伺服器錯誤

分頁

code
GET /users?page=1&limit=20
GET /users?offset=0&limit=20
GET /users?cursor=abc123

篩選與排序

code
GET /users?role=admin&status=active
GET /users?sort=created_at&order=desc
GET /users?fields=id,name,email

版本控制

code
# URL 路徑
GET /api/v1/users
GET /api/v2/users

# Header
Accept: application/vnd.api+json; version=1

認證

Bearer Token

code
Authorization: Bearer <token>

API Key

code
X-API-Key: <key>