68 lines
1.3 KiB
Markdown
68 lines
1.3 KiB
Markdown
---
|
|
name: REST API设计
|
|
description: RESTful接口设计原则
|
|
version: 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
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 123,
|
|
"name": "John Doe"
|
|
},
|
|
"meta": {
|
|
"page": 1,
|
|
"total": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
```json
|
|
{
|
|
"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
|