HTTP接口设计

作者 | 陌无崖

转载请联系授权

HTTP/2

一个HTTP/2连接是运行在TCP连接上的应用层协议。客户端是TCP连接的发起者。

请求方法

  • 如果请求头中存在 X-HTTP-Method-Override 或参数中存在 _method(拥有更高权重),且值为 GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD 之一,则视作相应的请求方式进行处理
  • GET, DELETE, HEAD 方法,参数风格为标准的 GET 风格的参数,如 url?a=1&b=2
  • POST,PUT,PATCH,OPTIONS方法
  • 默认情况下请求实体会被视作标准 json 字符串进行处理,当然,依旧推荐设置头信息的 Content-Typeapplication/json
  • 在一些特殊接口中(会在文档中说明),可能允许 Content-Typeapplication/x-www-form-urlencoded 或者 multipart/form-data ,此时请求实体会被视作标准 POST 风格的参数进行处理

关于方法语义的说明:

  • OPTIONS 用于获取资源支持的所有 HTTP 方法
  • HEAD 用于只获取请求某个资源返回的头信息
  • GET用于从服务器获取某个资源的信息
  • 完成请求后返回状态码 200 OK
  • 完成请求后需要返回被请求的资源详细信息
  • POST用于创建新资源
  • 创建完成后返回状态码 201 Created
  • 完成请求后需要返回被创建的资源详细信息
  • PUT用于完整的替换资源或者创建指定身份的资源,比如创建 id 为 123 的某个资源
  • 如果是创建了资源,则返回 201 Created
  • 如果是替换了资源,则返回 200 OK
  • 完成请求后需要返回被修改的资源详细信息
  • PATCH用于局部更新资源
  • 完成请求后返回状态码 200 OK
  • 完成请求后需要返回被修改的资源详细信息
  • DELETE用于删除某个资源
  • 完成请求后返回状态码 204 No Content

状态码

请求成功

  • 200 OK : 请求执行成功并返回相应数据,如 GET 成功
  • 201 Created : 对象创建成功并返回相应资源数据,如 POST 成功;创建完成后响应头中应该携带头标 Location ,指向新建资源的地址
  • 202 Accepted : 接受请求,但无法立即完成创建行为,比如其中涉及到一个需要花费若干小时才能完成的任务。返回的实体中应该包含当前状态的信息,以及指向处理状态监视器或状态预测的指针,以便客户端能够获取最新状态。
  • 204 No Content : 请求执行成功,不返回相应资源数据,如 PATCHDELETE 成功。

重定向

重定向的新地址都需要在响应头 Location 中返回

  • 301 Moved Permanently : 被请求的资源已永久移动到新位置
  • 302 Found : 请求的资源现在临时从不同的 URI 响应请求
  • 303 See Other : 对应当前请求的响应可以在另一个 URI 上被找到,客户端应该使用 GET 方法进行请求。比如在创建已经被创建的资源时,可以返回 303
  • 307 Temporary Redirect : 对应当前请求的响应可以在另一个 URI 上被找到,客户端应该保持原有的请求方法进行请求。

条件请求

  • 304 Not Modified : 资源自从上次请求后没有再次发生变化,主要使用场景在于实现数据缓存
  • 409 Conflict : 请求操作和资源的当前状态存在冲突。主要使用场景在于实现并发控制
  • 412 Precondition Failed : 服务器在验证在请求的头字段中给出先决条件时,没能满足其中的一个或多个。主要使用场景在于实现并发控制

客户端错误

  • 400 Bad Request : 请求体包含语法错误
  • 401 Unauthorized : 需要验证用户身份,如果服务器就算是身份验证后也不允许客户访问资源,应该响应 403 Forbidden。如果请求里有 Authorization 头,那么必须返回一个 `WWW-Authenticate` 头
  • 403 Forbidden : 服务器拒绝执行
  • 404 Not Found : 找不到目标资源
  • 405 Method Not Allowed : 不允许执行目标方法,响应中应该带有 Allow 头,内容为对该资源有效的 HTTP 方法
  • 406 Not Acceptable : 服务器不支持客户端请求的内容格式,但响应里会包含服务端能够给出的格式的数据,并在 Content-Type 中声明格式名称
  • 410 Gone : 被请求的资源已被删除,只有在确定了这种情况是永久性的时候才可以使用,否则建议使用 404 Not Found
  • 413 Payload Too Large : POST 或者 PUT 请求的消息实体过大
  • 415 Unsupported Media Type : 服务器不支持请求中提交的数据的格式
  • 422 Unprocessable Entity : 请求格式正确,但是由于含有语义错误,无法响应
  • 428 Precondition Required : 要求先决条件,如果想要请求能成功必须满足一些预设的条件

服务端错误

  • 500 Internal Server Error : 服务器遇到了一个未曾预料的状况,导致了它无法完成对请求的处理。
  • 501 Not Implemented : 服务器不支持当前请求所需要的某个功能。
  • 502 Bad Gateway : 作为网关或者代理工作的服务器尝试执行请求时,从上游服务器接收到无效的响应。
  • 503 Service Unavailable : 由于临时的服务器维护或者过载,服务器当前无法处理请求。这个状况是临时的,并且将在一段时间以后恢复。如果能够预计延迟时间,那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间(内容可以为数字,单位为秒;或者是一个 HTTP 协议指定的时间格式)。如果没有给出这个 Retry-After 信息,那么客户端应当以处理 500 响应的方式处理它。

501405 的区别是:405 是表示服务端不允许客户端这么做,501 是表示客户端或许可以这么做,但服务端还没有实现这个功能

身份验证

OAuth 2.0

  • 官网
  • 理解OAuth 2.0 - 阮一峰 以及对文中 `state` 参数的介绍的修正
  • JSON Web Token,一种 Token 的生成标准
  • Json Web Tokens: Introduction
  • Json Web Tokens: Examples

数据缓存

大部分接口应该在响应头中携带 Last-Modified, ETag, Vary, Date 信息,客户端可以在随后请求这些资源的时候,在请求头中使用 If-Modified-Since, If-None-Match 等请求头来确认资源是否经过修改。

如果资源没有进行过修改,那么就可以响应 304 Not Modified 并且不在响应实体中返回任何内容。

$ curl -i http://api.example.com/#{RESOURCE_URI}
HTTP/1.1 200 OK
Cache-Control: public, max-age=60
Date: Thu, 05 Jul 2012 15:31:30 GMT
Vary: Accept, Authorization
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
Content
$ curl -i http://api.example.com/#{RESOURCE_URI} -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60
Date: Thu, 05 Jul 2012 15:31:45 GMT
Vary: Accept, Authorization
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
$ curl -i http://api.example.com/#{RESOURCE_URI} -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60
Date: Thu, 05 Jul 2012 15:31:55 GMT
Vary: Accept, Authorization
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT

相关资料:

  • RFC 7232
  • HTTP 缓存 - Google Developers
  • RFC 2616 中缓存过期时间的算法, MDN 版, 中文版
  • HTTP 协议中 Vary 的一些研究
  • Cache Control 與 ETag

并发控制

不严谨的实现,或者缺少并发控制的 PUTPATCH 请求可能导致 “更新丢失”。这个时候可以使用 Last-Modified 和/或 ETag 头来实现条件请求,支持乐观并发控制。 下文只考虑使用 PUTPATCH 方法更新资源的情况。

  • 客户端发起的请求如果没有包含 If-Unmodified-Since 或者 If-Match 头,那就返回状态码 403 Forbidden ,在响应正文中解释为何返回该状态码
  • 客户端发起的请求提供的 If-Unmodified-Since 或者 If-Match 头与服务器记录的实际修改时间或 ETag 值不匹配的时候,返回状态码 412 Precondition Failed
  • 客户端发起的请求提供的 If-Unmodified-Since 或者 If-Match 头与服务器记录的实际修改时间或 ETag 的历史值匹配,但资源已经被修改过的时候,返回状态码 409 Conflict
  • 客户端发起的请求提供的条件符合实际值,那就更新资源,响应 200 OK 或者 204 No Content ,并且包含更新过的 Last-Modified 和/或 ETag 头,同时包含 Content-Location 头,其值为更新后的资源 URI

相关资料:

  • 《RESTful Web Services Cookbook 中文版》 10.4 节 《如何在服务器端实现条件 PUT 请求》
  • RFC 7232 "Conditional Requests"
  • Location vs. Content-Location

跨域

CORS

接口支持“跨域资源共享”(Cross Origin Resource Sharing, CORS),这里和这里和这份中文资料有一些指导性的资料。 简单示例:

$ curl -i https://api.example.com -H "Origin: http://example.com"
HTTP/1.1 302 Found
$ curl -i https://api.example.com -H "Origin: http://example.com"
HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-Total-Count
Access-Control-Allow-Credentials: true

预检请求的响应示例:

$ curl -i https://api.example.com -H "Origin: http://example.com" -X OPTIONS
HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-Total-Count
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true

JSON-P

如果在任何 GET 请求中带有参数 callback ,且值为非空字符串,那么接口将返回如下格式的数据

$ curl http://api.example.com/#{RESOURCE_URI}?callback=foo
foo({
  "meta": {
    "status": 200,
    "X-Total-Count": 542,
    "Link": [
      {"href": "http://api.example.com/#{RESOURCE_URI}?cursor=0&count=100", "rel": "first"},
      {"href": "http://api.example.com/#{RESOURCE_URI}?cursor=90&count=100", "rel": "prev"},
      {"href": "http://api.example.com/#{RESOURCE_URI}?cursor=120&count=100", "rel": "next"},
      {"href": "http://api.example.com/#{RESOURCE_URI}?cursor=200&count=100", "rel": "last"}
    ]
  },
  "data": // data
})

本文分享自微信公众号 - golang技术杂文(gh_ebbdb61f463e),作者:无崖子天下无敌

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-11-11

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • PHY_MDIO 接口设计

    在以太网通信中,设备之间的物理局链路均由 PHY 芯片建立。PHY 芯片内部含有一些列寄存器,用户可通过这些寄存器来配置 PHY 芯片的工作模式以及获取 PHY...

    碎碎思
  • API接口TOKEN设计

    首先需要知道API是什么? API(Application Programming Interface)即应用程序接口。你可以认为 API 是一个软件组件或是一...

    wangxl
  • 接口用例设计

    一个系统可为其他系统提供能力或者直接为UI层提供数据,在设计系统测试方案时应考虑上游调用的各种场景,不仅考虑顺利且正向思维操作的场景,还应逆向的场景。例如:人为...

    测试开发社区
  • 面向接口设计与角色接口

    问题:在做项目的时候,是不是所有包含非静态方法的类,都要写一个接口?是因为这样的目的是为了解耦,然后通过DI注入实现吗?

    张逸
  • SDK设计心得之接口设计

    子勰
  • RESTful 接口设计指南

    网络应用程序,分为前端和后端两个部分,当前的发展趋势,就是前端设备层出不穷,如手机、平板、桌面电脑等等。

    越陌度阡
  • API 接口设计规范

    调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用)。

    新亮
  • RobotFrameWork接口设计规范

    继前面一章《RobotFramework环境搭建》介绍了在本地如何将接口自动化实施过程所需要的基础环境搭建好,在这里假设大家都已经知道环境如何搭建了,如果不清...

    测试开发技术
  • API接口设计规范

    说明:在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取)?除了https的协议之外,能不能加上通用的一套算法...

    Java旅途
  • 架构设计 - 日志管理接口设计

    Aichen
  • 架构设计 - 日志管理接口设计

    Aichen
  • FreeSWITCH中的HTTP接口

    HTTP协议是当今最流行的通信协议。FreeSWITCH即可以作为一个HTTP Client,也可以作为一个HTTP Server与其它系统对接。

    Seven Du
  • 接口测试用例设计

    随着测试分析和分层测试的深化,“接口测试”出现在我们视野的频次越来越高。那么接口测的用例设计常用哪些方法呢?本文将详细描述。

    腾讯移动品质中心TMQ
  • 接口设计六大原则

    子勰
  • P2P接口串行FIR设计

    配置接口使用寄存器组实现,掉电丢失,因此每次使用之前需要进行配置FIR参数,配置接口时序如下所示:

    月见樽
  • 设计模式-流畅接口

    感觉上面起来都有些啰嗦,看了下QString文档,QString的append接口调用后返回自己的引用,那么就可以这样写。

    Qt君
  • 接口测试平台中接口内容的设计

    这部分主要是该条case的一些基础信息,例如创建人、最后更新人(同时也是最后调试过该case的人)。因为我们的平台有一个登录系统,所以所有case在被创建和被编...

    软件测试君
  • APP架构设计经验谈:接口的设计

    App与服务器的通信接口如何设计得好,需要考虑的地方挺多的,在此根据我的一些经验做一些总结分享,旨在抛砖引玉。

    lyb-geek
  • 像设计马桶一样设计接口 No.109

    我发现很多人,包括我自己,在设计接口和流程的时候,都希望接口保持最小职责原则,因为我们是"平台",我们只能提供最小粒度的接口。

    大蕉

扫码关注云+社区

领取腾讯云代金券