api-design

Zate 的头像作者 Zate

设计RESTful和GraphQL API的最佳实践。涵盖端点命名、版本控制、错误处理、分页和文档。设计新API或审查现有API时使用。

📖 中文导读:设计RESTful和GraphQL API的最佳实践。涵盖端点命名、版本控制、错误处理、分页和文档。设计新API或审查现有API时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: api-design description: This skill should be used for REST API, GraphQL, versioning, pagination, authentication, backend routes, web services, HTTP endpoints, server API design whenToUse: API design, endpoints, REST patterns, backend development, web services, HTTP routes, server-side endpoints, Express routes, FastAPI endpoints whenNotToUse: Internal interfaces, non-HTTP APIs, frontend-only code seeAlso:

  • skill: security-checklist when: securing API endpoints
  • skill: architecture-patterns when: designing API layer architecture
  • skill: database-patterns when: API data modeling

API Design

REST API design best practices.

URL Structure

GET    /users          # List
GET    /users/:id      # Get one
POST   /users          # Create
PUT    /users/:id      # Replace
PATCH  /users/:id      # Update
DELETE /users/:id      # Delete

Versioning

/api/v1/users          # URL versioning
Accept: application/vnd.api.v1+json  # Header

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{"field": "email", "issue": "invalid format"}]
  }
}

Status Codes

Code Use
200 Success
201 Created
400 Bad request
401 Unauthorized
404 Not found
500 Server error