设计 HTTP API 的最佳实践

HTTP 请求方法

当客户端向服务器发起 HTTP 请求的时候，请求的 Header 中会有一个字段叫 Request Method，也叫做 HTTP verb，不同的 HTTP verbs 表达了不同的 HTTP 请求意图，而我们常用的，有下面这几种：

GET：表示客户端需要请求服务器的某个资源。简单来说，就是当我们需要给用户显示某些保存在服务器上的内容时，都会向服务器发起 GET 请求
POST：表示向服务器提交数据，例如用户注册时填写的信息、登录时填写的用户名 / 密码等。简单来说，就是当我们需要根据用户输入在服务器上创建新记录的时候，都会向服务器发起 POST 请求
PUT：表示根据用户提供的内容，修改服务器上的特定资源；PUT 请求修改要求提供的数据是全量的，例如当我们修改某条数据库记录时，使用 PUT 请求，应该包含这条记录的所有字段，这种修改更像是覆盖
PATCH：使用 PATCH 请求提交的内容则是有针对性的，只要提供需要的部分就好了
DELETE: 请求服务器删除指定的页面
CONNECT: HTTP/1.1 协议中预留给能够将连接改为管道方式的代理服务器
OPTIONS: 允许客户端查看服务器的性能
TRACE: 回显服务器收到的请求，主要用于测试或诊断
PATCH: 是对 PUT 方法的补充，用来对已知资源进行局部更新

HTTP 状态码

当浏览者访问一个网页时，浏览者的浏览器会向网页所在服务器发出请求。当浏览器接收并显示网页前，此网页所在的服务器会返回一个包含 HTTP 状态码的信息头（server header）用以响应浏览器的请求。
HTTP 状态码的英文为 HTTP Status Code。。
下面是 HTTP 状态码分类：

1** - 信息，服务器收到请求，需要请求者继续执行操作
2** - 成功，操作被成功接收并处理
3** - 重定向，需要进一步的操作以完成请求
4** - 客户端错误，请求包含语法错误或无法完成请求
5** - 服务器错误，服务器在处理请求的过程中发生了错误

HTTP 状态码列表

状态码	状态码英文	中文描述
`100`	Continue	继续。客户端应继续其请求
`101`	Switching Protocols	切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到 HTTP 的新版本协议

状态码	状态码英文	中文描述
`200`	OK	请求成功。一般用于 GET 与 POST 请求
`201`	Created	已创建。成功请求并创建了新的资源
`202`	Accepted	已接受。已经接受请求，但未处理完成
`203`	Non-Authoritative Information	非授权信息。请求成功。但返回的 meta 信息不在原始的服务器，而是一个副本
`204`	No Content	无内容。服务器成功处理，但未返回内容。在未更新网页的情况下，可确保浏览器继续显示当前文档
`205`	Reset Content	重置内容。服务器处理成功，用户终端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域
`206`	Partial Content	部分内容。服务器成功处理了部分 GET 请求

状态码	状态码英文	中文描述
`301`	Moved Permanently	永久移动。请求的资源已被永久的移动到新 URI，返回信息会包括新的 URI，浏览器会自动定向到新 URI。今后任何新的请求都应使用新的 URI 代替
`302`	Found	临时移动。与 301 类似。但资源只是临时被移动。客户端应继续使用原有 URI
`303`	See Other	查看其它地址。与 301 类似。使用 GET 和 POST 请求查看
`304`	Not Modified	未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源
`305`	Use Proxy	使用代理。所请求的资源必须通过代理访问
`306`	Unused	已经被废弃的 HTTP 状态码
`307`	Temporary Redirect	临时重定向。与 302 类似。使用 GET 请求重定向

状态码	状态码英文	中文描述
`400`	Bad Request	客户端请求的语法错误，服务器无法理解
`401`	Unauthorized	请求要求用户的身份认证
`402`	Payment Required	保留，将来使用
`403`	Forbidden	服务器理解请求客户端的请求，但是拒绝执行此请求
`404`	Not Found	服务器无法根据客户端的请求找到资源（网页）。通过此代码，网站设计人员可设置” 您所请求的资源无法找到” 的个性页面
`405`	Method Not Allowed	客户端请求中的方法被禁止
`406`	Not Acceptable	服务器无法根据客户端请求的内容特性完成请求
`407`	Proxy Authentication Required	请求要求代理的身份认证，与 401 类似，但请求者应当使用代理进行授权
`408`	Request Time-out	服务器等待客户端发送的请求时间过长，超时
`409`	Conflict	服务器完成客户端的 PUT 请求时可能返回此代码，服务器处理请求时发生了冲突
`410`	Gone	客户端请求的资源已经不存在。410 不同于 404，如果资源以前有现在被永久删除了可使用 410 代码，网站设计人员可通过 301 代码指定资源的新位置
`411`	Length Required	服务器无法处理客户端发送的不带 Content-Length 的请求信息
`412`	Precondition Failed	客户端请求信息的先决条件错误
`413`	Request Entity Too Large	由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个 Retry-After 的响应信息
`414`	Request-URI Too Large	请求的 URI 过长（URI 通常为网址），服务器无法处理
`415`	Unsupported Media Type	服务器无法处理请求附带的媒体格式
`416`	Requested range not satisfiable	客户端请求的范围无效
`417`	Expectation Failed	服务器无法满足 Expect 的请求头信息

状态码	状态码英文	中文描述
`500`	Internal Server Error	服务器内部错误，无法完成请求
`501`	Not Implemented	服务器不支持请求的功能，无法完成请求
`502`	Bad Gateway	作为网关或者代理工作的服务器尝试执行请求时，从远程服务器接收到了一个无效的响应
`503`	Service Unavailable	由于超载或系统维护，服务器暂时的无法处理客户端的请求。延时的长度可包含在服务器的 Retry-After 头信息中
`504`	Gateway Time-out	充当网关或代理的服务器，未及时从远端服务器获取请求
`505`	HTTP Version not supported	服务器不支持请求的 HTTP 协议的版本，无法完成处理

Naming conventions

了解了 HTTP verbs 之后，我们来看设计 HTTP APIs 时应遵信的一些命名规范。其中，最重要的一个大原则就是，永远使用名词表示 API 管理的资源。

文档类型的 API：用于访问服务器上的某一个文件，或者某一条数据记录，因此，我们应该以单数名词结尾，或者以一个复数名词加上一个与之有关的值，例如：
plaintext
https://api.soyl.com/episodes/{id}
https://api.soyl.com/accounts/admin
集合类型的 API：用于访问服务器上的某一类内容，例如数据库中的某个记录集合。定义这一类 API 的时候，除了在 URL 中使用复数名词之外，整个 URL 中还应该包含访问到这个集合时用到的每一个资源的名称
plaintext
https://api.soyl.com/series/{id}/episodes
集合的筛选的 API：如果我们要让 API 支持集合的筛选，就不要使用 / 来设置条件了，而是应该在 URL 末尾添加条件查询。例如，为了得到所有按月订阅的会员，我们可以这样：
plaintext
https://api.soyl.com/users?sub-type=month
和控制行为有关的 API：这是为数不多的，我们会在 URL 中使用动词的例子。例如，为了结算用户的购物车，在结尾，我们使用了 /cart/check 这样的形式，这很类似面向对象编程中的访问 cart 对象的 checkout 方法的感觉。一旦看到这种形式的 API，我们就知道它会在服务器执行某个动作，而不是管理某些资源。
plaintext
https://api.soyl.com/users/{id}/cart/checkout
再来看个例子，如果要播放某个视频，我们可以这样：
plaintext
https://api.boxue.io/series/{id}/episodes/{id}/play
这个 API 可以分几段来理解：
- 第一段是 /series/{id}，我们可以把它想象成是一个叫做 series 的方法，它接受一个参数 id，并返回一个集合，包含了改系列所有的视频；
- 第二段是 /episodes/{id}，类似的，我们使用 id 作为索引，访问到了集合中的某个视频对象；
- 第三段是 /play，可以理解成是调用了视频对象的 play 方法执行播放；
  这样，整个 URL 的含义就很清楚了。