gh-743175724-agents-project-plugins-web-development/plugins/web-development/skills/rest-api-design.md

name, description, version

name	description	version
REST API设计	RESTful接口设计原则	1.0.0

RESTful API Design Principles

Resource Naming

GET    /api/v1/users          # List users
POST   /api/v1/users          # Create user
GET    /api/v1/users/:id      # Get user
PUT    /api/v1/users/:id      # Update user
DELETE /api/v1/users/:id      # Delete user

# Nested resources
GET    /api/v1/users/:id/posts

HTTP Status Codes

• 200 OK: Success
• 201 Created: Resource created
• 204 No Content: Success, no body
• 400 Bad Request: Invalid input
• 401 Unauthorized: Not authenticated
• 403 Forbidden: Authenticated but no permission
• 404 Not Found: Resource doesn't exist
• 500 Internal Server Error: Server error

Response Format

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John Doe"
  },
  "meta": {
    "page": 1,
    "total": 100
  }
}

Error Handling

{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Best Practices

• Use nouns, not verbs in URLs
• Version your API (/v1/, /v2/)
• Use query parameters for filtering/sorting
• Implement pagination
• Support ETag for caching
• Document with OpenAPI/Swagger