设计原则 📌

  • 一致性:保持接口行为、参数命名和响应格式统一,例如使用GET请求获取数据,POST用于创建资源。
  • 简洁性:避免冗余字段,如/api/users/123/api/users?id=123更直观。
  • 版本控制:在路径中添加版本号(如/api/v1/guide),确保兼容性。
api_design_guide

请求结构 📦

  • 方法GETPOSTPUTDELETE等HTTP方法需与操作匹配。
  • 参数
    • 查询参数(Query Parameters):如/api/products?category=electronics
    • 请求头(Headers):设置Content-Typeapplication/json
    • 请求体(Body):仅适用于POST/PUT,如{"name": "Test", "price": 99.99}

响应规范 📈

  • 状态码
    • 200:成功
    • 404:资源未找到
    • 500:服务器内部错误
  • 数据格式:使用JSON,确保字段命名清晰(如data包裹响应内容)。
api_design_principles

安全机制 🔒

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

扩展阅读 📚

api_security_measures