RESTful API 设计指南(4)——如何实现RESTful API（上）

前言

在前面一系列的文章中，我们介绍了 RESTful API 出现的背景，以及为什么要引入 RESTful API 风格。那么从本章开始，我们将进入实现篇，在本篇中，我们主要关注如何实现 RESTful API 风格。

所以，其背后是一个对 HTTP 协议进行再学习的过程，本质上就是要用好 HTTP 协议：

• 设计好 URL 和 HTTP 主体（path和body）：充分利用 URL 的 path 和 query 部分，path 中代表要操作的资源（对象），query放查询条件，body中放请求参数和响应结果
• 正确选择 HTTP 方法（method）：平常你可能只使用 GET 和 POST 方法，但是 HTTP 协议中还提供了 DELETE、PUT 和 OPTION 等方法。所以，REST 风格中就充分利用了 HTTP 应用层协议的特性，把增删改查分别对应到 HTTP 的 POST、DEELTE、PUT和GET方法上。
• 正确选择 HTTP 状态码（status code）：正确的使用状态码，当因为客户端参数异常而发生错误，应当返回 400 Bad Request，如果是服务端内部原因发生错误，应当返回 500 Internal Server Error，如果修改成功，通常情况下应当返回 204 No Content。
• 充分利用 HTTP 报头（request header)：一些通用的参数应当优先考虑放在 HTTP 报头中，比如接口认证，每个接口都需要携带 token，可以使用 Authorization 这个报头。

下面，让我们再复习一下 HTTP 协议的这几个关键部分。

URL

URL 是 URI 的一个子集，特指 HTTP 协议中的资源定位符，URI格式定义如下：

bash

代码解读

复制代码

hierarchical part ┌───────────────────┴─────────────────────┐ authority path ┌───────────────┴───────────────┐┌───┴────┐ abc://username:[email protected]:123/path/data?key=value&key2=value2#fragid1 └┬┘ └───────┬───────┘ └────┬────┘ └┬┘ └─────────┬─────────┘ └──┬──┘ scheme user information host port query fragment

根据 RFC 3986 文档：

• scheme：协议标识符，用于表示访问资源的具体协议，如下是几个示例：
  • http：www.example.com，表示通过 HTTP 协议访问 www.example.com。
  • https：secure.example.com，表示通过 HTTPS 协议（HTTP 的安全版本）访问 secure.example.com。
  • ftp：