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管理的资源。

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

API的细节

  1. 不要在URL中使用_，很难只用一个单词来描述URL中的一个环节，这时，就可以使用-来分割多个单词，而不是用_
  2. 始终坚持使用小写字母，RFC 3986约定了：对于URL来说，SCHEME和HOST部分是不区分大小写的；而其余的部分是区分大小写的
  3. 不要在URL中包含扩展名

参考引用

  1. Runoob.com