HTTP API设计 第二部分—Responses

写在前面

基于协议的是时下最为流行的一种分布式服务提供方式。之前在审查写的 的时候有些东西没理解清楚,后来查阅一些资料的时候看到 在17年6月份发表介绍设计的四篇文章(,,,)和该作者写的一本小册子,内容比较清晰,所以打算翻译下保留下来。第一次翻译这么长的文章,文字功底也比较拙劣...orz

HTTP应答简介

服务端收到一个客户端请求之后总会返回一个回复(排除一些特别严重情况的发生)。应答消息格式和请求消息格式类似,不过还是有不少的区别。下面是一个完整的消息回复:

第一行是状态行,包含两个信息。第一个是协议信息,这里是,接下来是个空格。第二个信息是请求状态,由一个机器可读的状态编码,一个空格和一个人可读的解析词,接下来是新的一行。解析词和状态编码是一一对应的,不过在大多数情况下都可以忽略这个过时字符串。

和请求一样,应答消息头里面也包含一系列的键值对,下面是新的一行。理论上来说头部信息可以是任何形式,不过严谨的服务端会返回首字母大写,使用连字符的词组。头部字段可以重复出现如果有多个值,比如单个应答里面有多个头部字段允许设置多个。

状态码用不同区间的数字区分,不同区间表示不同类型的状态。文中接下来描述了不同的数字区间和区间里面的数值含义。

头部最下面是可选的消息体,消息体前面需要有两个空行。几乎所有的应答都会包含一个消息体,即使理论上是可选的。

1XX Status Codes – Informational

区间(100-199)里面的数字表示报告状态码。我们整个职业生涯永远不需要处理这个区间里面的状态码。

: used for websockets

2XX Status Codes – Successful

区间(200-299)里面的数字表示成功状态码。反馈给客户端的信息就是操作成功了,无论是创建一个资源或者是简单的获取一个资源。理论上来说它们是最常被使用的状态码。

200 OK: 可以代表所有操作都成功。

201 Created: 资源被创建。

202 Accepted: 创建或更新资源成功,不过操作是异步的。

204 No Content: 请求成功,不过没有请求体。

3XX Status Codes – Redirection

区间(300-399)里面的数字表示客户端需要重定向。不包含消息体,会有一个的消息头,包含了一个客户端需要重定向的。

301 Moved Permanently: 资源被移动到另外一个新地址,需要访问新地址。

302 Found: 资源在新地址,不过每次还是需要检查下旧地址。

4XX Status Codes – Client Error

区间(400-499)里面的数字表示客户端错误。当一个的请求返回该区间的状态码,那么这个请求一般还没有改变服务端状态。

400 Invalid Request: 一般的客户端错误

401 Unauthorized: 客户端需要提供权限认证请求头

403 Forbidden: 客户端禁止访问该资源

404 Not Found: 资源不存在

405 Method Not Allowed: 请求路径存在,只是不支持该请求类型

406 Not Acceptable: 服务端无法对请求头里面的类型产生应答

5XX Status Codes – Server Error

区间(500-599)里面的数字表示服务端错误。当返回这类错误很可能是服务端发生错误,也许请求根本没被接收。如果一个请求返回该状态,就无法知道服务端的状态了。这类的错误应当不计成本的被避免出现。

500 Internal Server Error:一般的服务端错误

501 Not Implemented: 服务端不支持该类型的请求路径

503 Service Unavailable: 服务端临时无法访问,可能是数据库断开了连接

521 Web Server Is Down: 中间服务器无法连接远程服务

应答头部

和请求类似,应答消息也有大量的头部字段可以使用。头部字段描述了应答的元数据信息。通常你可直接使用标准的头部字段,不过有时候你需要自建字段,以开头,例如。下面列出了常见的字段:

Cache-Control: 缓存设置,比如如果资源不应该被缓存

Content-Language: 消息体语言,比如

Content-Length: 消息体长度,如果一开始就知道

Content-Type: 消息体类型,比如

Date: 服务器时间

Expires: 消息体过期时间

Server: 很少用到,被用来标识服务器

  • 发表于:
  • 原文链接:http://kuaibao.qq.com/s/20180104G0YV8G00?refer=cp_1026

同媒体快讯

扫码关注云+社区