api-design

Name: api-design
Rating: 76
Author: Zate

此技能适用于 REST API、GraphQL、版本控制、分页机制、身份认证、后端路由、Web 服务、HTTP 端点以及服务器 API 设计。

SKILL.md

--- frontmatter

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

code

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

Versioning

code

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

Pagination

json

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

Error Responses

json

{
  "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