名称：rest-api-design
描述：设计具有适当资源命名、HTTP方法、状态码和响应格式的RESTful API。在构建新API、建立API约定或设计开发者友好界面时使用。
REST API 设计
设计具有适当约定和开发者体验的RESTful API。
资源命名
# 好 - 名词，复数，层次化
GET /api/users
GET /api/users/123
GET /api/users/123/orders
POST /api/users
PATCH /api/users/123
DELETE /api/users/123
# 坏 - 动词，URL中的动作
GET /api/getUsers
POST /api/createUser
POST /api/users/123/delete
HTTP 方法
| 方法 |
目的 |
幂等性 |
| GET |
读取资源 |
是 |
| POST |
创建资源 |
否 |
| PUT |
替换资源 |
是 |
| PATCH |
部分更新 |
是 |
| DELETE |
删除资源 |
是 |
状态码
| 代码 |
含义 |
用途 |
| 200 |
OK |
成功的GET、PATCH |
| 201 |
Created |
成功的POST |
| 204 |
No Content |
成功的DELETE |
| 400 |
Bad Request |
验证错误 |
| 401 |
Unauthorized |
缺少认证 |
| 403 |
Forbidden |
权限不足 |
| 404 |
Not Found |
资源不存在 |
| 429 |
Too Many Requests |
速率限制 |
响应格式
{
"data": {
"id": "123",
"type": "user",
"attributes": {
"name": "John",
"email": "john@example.com"
}
},
"meta": {
"requestId": "req_abc123"
}
}
集合响应
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
},
"links": {
"self": "/api/users?page=1",
"next": "/api/users?page=2"
}
}
查询参数
GET /api/products?category=electronics # 过滤
GET /api/products?sort=-price,name # 排序
GET /api/products?page=2&limit=20 # 分页
GET /api/products?fields=id,name,price # 字段选择
最佳实践
- 使用名词表示资源，而不是动词
- 通过URL路径版本化API (
/api/v1/)
- 返回适当的状态码
- 为集合包括分页
- 使用OpenAPI/Swagger进行文档化