作者 | 陌无崖
转载请联系授权
一个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
方法Content-Type
为 application/json
Content-Type
为 application/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
GET
成功POST
成功;创建完成后响应头中应该携带头标 Location
,指向新建资源的地址PATCH
, DELETE
成功。重定向的新地址都需要在响应头 Location
中返回
GET
方法进行请求。比如在创建已经被创建的资源时,可以返回 303
403 Forbidden
。如果请求里有 Authorization
头,那么必须返回一个 `WWW-Authenticate` 头Allow
头,内容为对该资源有效的 HTTP 方法Content-Type
中声明格式名称404 Not Found
POST
或者 PUT
请求的消息实体过大Retry-After
头用以标明这个延迟时间(内容可以为数字,单位为秒;或者是一个 HTTP 协议指定的时间格式)。如果没有给出这个 Retry-After
信息,那么客户端应当以处理 500 响应的方式处理它。501
与 405
的区别是:405
是表示服务端不允许客户端这么做,501
是表示客户端或许可以这么做,但服务端还没有实现这个功能
OAuth 2.0
大部分接口应该在响应头中携带 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
相关资料:
不严谨的实现,或者缺少并发控制的 PUT
和 PATCH
请求可能导致 “更新丢失”。这个时候可以使用 Last-Modified
和/或 ETag
头来实现条件请求,支持乐观并发控制。
下文只考虑使用 PUT
和 PATCH
方法更新资源的情况。
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相关资料:
接口支持“跨域资源共享”(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
如果在任何 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
})