RESTful API

概念与基础

RESTful API 简介

  • 定义：RESTful API 是一种基于 HTTP 协议的应用程序接口，遵循 REST 架构风格。
  • 特点：
    • 无状态：每个请求都是独立的，服务器不会存储客户端的状态。
    • 统一接口：使用标准的 HTTP 方法（GET、POST、PUT、DELETE）。
    • 可缓存：HTTP 协议内置缓存机制。
    • 分层系统：客户端无法直接感知到中间层。

HTTP 方法与操作

  • GET：检索资源，不应改变服务器状态。
  • POST：创建资源，通常会改变服务器状态。
  • PUT：更新资源，通常是幂等操作。
  • DELETE：删除资源。

URI 设计原则

  • 简洁明了：URI 应该直观且易读，例如 /users/{id}。
  • 使用名词而非动词：URI 中应用名词来表示资源，而不是动作。
  • 层级结构反映关系：利用路径层级反映资源之间的关系。

设计与实现

状态码意义

  • 200 OK：请求成功，一般用于 GET 和 PUT 请求。
  • 201 Created：请求成功并且创建了新的资源，用于 POST 请求。
  • 204 No Content：请求成功但无返回内容，用于 DELETE 请求成功后。
  • 400 Bad Request：客户端请求无效，服务器无法处理该请求。
  • 404 Not Found：所请求的资源不存在。

常见头信息

  • Content-Type: 指定传输数据的媒体类型，例如 application/json。
  • Accept: 客户端期望接收的数据格式，例如 application/json。

安全与认证

身份认证方法

  • Basic Auth: 基本认证，通过在头信息中携带用户名和密码进行认证，不够安全。
  • Bearer Token（JWT）: 使用 JSON Web Token，在每次请求时携带 token 用于验证身份。

授权机制

  • 使用 OAuth2.0 用于第三方应用授权访问用户数据，而不需要暴露用户凭证。

最佳实践

版本控制

通过在 URI 中包含版本号来管理 API 的不同版本，例如 /api/v1/users。

错误处理

返回详细错误消息，包括错误码和描述，以便客户端能够理解问题所在并进行相应处理。