设计原则 📌

  • 一致性：保持接口行为、参数命名和响应格式统一，例如使用GET请求获取数据，POST用于创建资源。
  • 简洁性：避免冗余字段，如/api/users/123比/api/users?id=123更直观。
  • 版本控制：在路径中添加版本号（如/api/v1/guide），确保兼容性。
api_design_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包裹响应内容）。
api_design_principles

安全机制 🔒

  • 认证：支持OAuth 2.0或JWT，路径示例/api/auth/token。
  • 权限：通过Authorization头验证用户角色（如Bearer <token>）。
  • 数据加密：敏感字段（如用户密码）需加密传输，路径/api/users/123可结合GET查询参数过滤数据。

扩展阅读 📚

api_security_measures