REST（Representational State Transfer）是一种软件架构风格，用于设计网络应用程序的接口。
REST API（Application Programming Interface）是基于 REST 原则构建的 Web 服务接口，它允许不同的系统通过 HTTP 协议进行通信和数据交换。
REST API 的核心特点包括：
在 REST 中，资源是任何可以命名的信息，如用户、产品、订单等。每个资源都有一个唯一的标识符（URI）。
REST API 使用标准 HTTP 方法来定义对资源的操作：
| HTTP 方法 | 描述 | 幂等性 | 安全性 |
|---|---|---|---|
| GET | 获取资源 | 是 | 是 |
| POST | 创建新资源 | 否 | 否 |
| PUT | 更新整个资源 | 是 | 否 |
| PATCH | 部分更新资源 | 否 | 否 |
| DELETE | 删除资源 | 是 | 否 |
HTTP 状态码表示请求的处理结果：
| 状态码 | 类别 | 常见状态码 |
|---|---|---|
| 2xx | 成功 | 200 OK, 201 Created |
| 3xx | 重定向 | 301 Moved Permanently |
| 4xx | 客户端错误 | 400 Bad Request, 404 Not Found |
| 5xx | 服务器错误 | 500 Internal Server Error |
REST API 常用的数据交换格式：
/users /getUsers/users/{id}/orders建议在 URI 或请求头中包含 API 版本信息：
/v1/usersAccept: application/vnd.myapi.v1+json对于集合资源，提供查询参数：
/users?role=admin/users?sort=-created_at/users?page=2&limit=10
# 获取用户列表
GET /api/v1/users
Accept: application/json
# 创建新用户
POST /api/v1/users
Content-Type: application/json
{
"name": "张三",
"email": "[email protected]"
}
# 获取特定用户
GET /api/v1/users/123
Accept: application/json
# 更新用户信息
PUT /api/v1/users/123
Content-Type: application/json
{
"name": "张三(更新)",
"email": "[email protected]"
}
# 删除用户
DELETE /api/v1/users/123
// 成功响应
{
"status": "success",
"data": {
"id": 123,
"name": "张三",
"email": "[email protected]",
"created_at": "2023-01-01T00:00:00Z"
}
}
// 错误响应
{
"status": "error",
"message": "User not found",
"code": 404
}
# GET 请求
curl -X GET https://api.example.com/users/123 \
-H "Accept: application/json"
# POST 请求
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"李四","email":"[email protected]"}'
根据编程语言不同，有多种框架可用于开发 REST API：
| 语言 | 流行框架 |
|---|---|
| JavaScript | Express.js, NestJS |
| Python | Django REST Framework, Flask |
| Java | Spring Boot |
| PHP | Laravel, Symfony |
| Ruby | Ruby on Rails |
| Go | Gin, Echo |
基本原则：
示例：
✅ 好的设计: /users, /products, /orders
❌ 不好的设计: /getUsers, /addProduct, /all-orders
扩展建议：
/companies/{companyId}/departments/{departmentId}/employees/shipping-addresses 而非 /shippingaddresses基本用法：
示例：
GET /users # 获取用户列表 GET /users/123 # 获取特定用户 POST /users # 创建新用户 PUT /users/123 # 完全更新用户 PATCH /users/123 # 部分更新用户 DELETE /users/123 # 删除用户
扩展建议：
POST /users/123/activate 比 POST /activateUser/123 更符合REST原则常用状态码：
扩展建议：
基本实现：
limit和offset或page和size参数示例：
GET /products?limit=20&offset=40 GET /products?page=3&size=20
响应示例：
{
"data": [...],
"pagination": {
"total": 523,
"pages": 27,
"current_page": 3,
"per_page": 20,
"next": "/products?page=4&size=20",
"prev": "/products?page=2&size=20"
}
}
扩展建议：
GET /events?since=2023-01-01T00:00:00Z&until=2023-01-31T23:59:59Z基本实现：
?status=activesort参数进行排序：?sort=created_at?sort=price:asc,rating:desc示例：
GET /products?category=electronics&price_min=100&price_max=500&sort=price:asc GET /users?role=admin&search=john
扩展建议：
?price=gt:100,lt:500?name=like:john?fields=id,name,email?filter=recent可能等同于?created_after=30days&sort=created_at:desc主要方法：
/api/v1/users/api/users?version=1Accept: application/vnd.company.v1+json扩展建议：
基本结构：
成功响应示例：
{
"status": "success",
"data": {
"id": 123,
"name": "Example Product",
"price": 99.99
},
"meta": {
"timestamp": "2023-06-15T08:30:00Z"
}
}
错误响应示例：
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{"field": "email", "message": "Must be a valid email address"}
]
},
"meta": {
"timestamp": "2023-06-15T08:30:00Z",
"request_id": "req-123456"
}
}
扩展建议：
基本概念：
示例：
{
"data": {
"id": 123,
"name": "John Doe"
},
"links": {
"self": "/users/123",
"orders": "/users/123/orders",
"update": {"href": "/users/123", "method": "PUT"},
"delete": {"href": "/users/123", "method": "DELETE"}
}
}
扩展建议：
常用格式：
扩展建议：
Accept头指定期望的格式常用方法：
扩展建议：
基本实现：
响应头示例：
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1623760800
扩展建议：
基本实现：
示例：
Cache-Control: max-age=3600, must-revalidate ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
扩展建议：
基本实现：
扩展建议：
基本实现：
扩展建议：
基本实现：
扩展建议：
基本实现：
扩展建议：
批量处理：
批量操作示例：
POST /users/batch
{
"operations": [
{"method": "POST", "path": "/users", "body": {"name": "User 1"}},
{"method": "PUT", "path": "/users/123", "body": {"name": "Updated User"}}
]
}
异步操作：
异步流程示例：
POST /reports/generate
Response: 202 Accepted
Location: /tasks/abc-123
GET /tasks/abc-123
Response: {"status": "processing", "progress": 45, "eta": "30s"}
GET /tasks/abc-123
Response: {"status": "completed", "result": "/reports/xyz-789"}
扩展建议：
基本原则：
扩展建议：
?fields=id,name,thumbnail设计良好的REST API需要仔细平衡多种因素，包括可用性、性能、安全性和可维护性。通过遵循这些最佳实践，开发团队可以创建既符合REST原则又满足现代应用需求的API。关键是保持一致性、直观性，并始终从API消费者的角度思考。随着API经济的不断发展，优质的API设计将成为组织成功的关键因素。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。