rest-api-design

secondsky 的头像作者 secondsky

设计RESTful API,包括适当的资源命名、HTTP方法、状态码和响应格式。适用于构建新API、建立API规范或设计开发者友好的界面。

📖 中文导读:设计RESTful API,包括适当的资源命名、HTTP方法、状态码和响应格式。适用于构建新API、建立API规范或设计开发者友好的界面。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: rest-api-design description: Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.

REST API Design

Design RESTful APIs with proper conventions and developer experience.

Resource Naming

# Good - nouns, plural, hierarchical
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/users
PATCH  /api/users/123
DELETE /api/users/123

# Bad - verbs, actions in URL
GET    /api/getUsers
POST   /api/createUser
POST   /api/users/123/delete

HTTP Methods

Method Purpose Idempotent
GET Read resource Yes
POST Create resource No
PUT Replace resource Yes
PATCH Partial update Yes
DELETE Remove resource Yes

Status Codes

Code Meaning Use For
200 OK Successful GET, PATCH
201 Created Successful POST
204 No Content Successful DELETE
400 Bad Request Validation errors
401 Unauthorized Missing auth
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limited

Response Format

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "john@example.com"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Collection Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}

Query Parameters

GET /api/products?category=electronics    # Filtering
GET /api/products?sort=-price,name        # Sorting
GET /api/products?page=2&limit=20         # Pagination
GET /api/products?fields=id,name,price    # Field selection

Best Practices

  • Use nouns for resources, not verbs
  • Version API via URL path (/api/v1/)
  • Return appropriate status codes
  • Include pagination for collections
  • Document with OpenAPI/Swagger