设计原则 📌
- 一致性:保持接口行为、参数命名和响应格式统一,例如使用
GET
请求获取数据,POST
用于创建资源。
- 简洁性:避免冗余字段,如
/api/users/123
比/api/users?id=123
更直观。
- 版本控制:在路径中添加版本号(如
/api/v1/guide
),确保兼容性。
请求结构 📦
- 方法:
GET
、POST
、PUT
、DELETE
等HTTP方法需与操作匹配。
- 参数:
- 查询参数(Query Parameters):如
/api/products?category=electronics
。
- 请求头(Headers):设置
Content-Type
为application/json
。
- 请求体(Body):仅适用于
POST
/PUT
,如{"name": "Test", "price": 99.99}
。
响应规范 📈
- 状态码:
200
:成功
404
:资源未找到
500
:服务器内部错误
- 数据格式:使用JSON,确保字段命名清晰(如
data
包裹响应内容)。
安全机制 🔒
- 认证:支持
OAuth 2.0
或JWT
,路径示例/api/auth/token
。
- 权限:通过
Authorization
头验证用户角色(如Bearer <token>
)。
- 数据加密:敏感字段(如用户密码)需加密传输,路径
/api/users/123
可结合GET
查询参数过滤数据。
扩展阅读 📚