返回首页
0
0

异步 API 的设计

大发排列3计划 发表于 2018年12月12日 08:31 | Hits: 954
Tag: Developer

网站的前后端通信,往往会有异步请求,这时应该怎么设计 API?

我最近读到一篇文章,作者介绍了他的做法,设计得很精细,我觉得值得借鉴,可以当作异步 API 的标准设计。

一、同步 API

为了便于比较,先看看同步 API 的设计。下面是一个很简单的例子。

客户端发出一个请求,要求创建资源。

POST http://api.service.io/stars

name='Death Star' 

服务器回应 201。

HTTP/1.1 201 Created
Location: /stars/12345

201 Created告诉客户端,请求成功,资源已经创建。新的资源的网址请看Location字段。

二、异步请求

如果服务器不能立即返回结果,就形成了异步操作。

客户端的请求还是一样的。

POST http://api.service.io/stars

name='Death Star' 

服务器回应 202。

HTTP/1.1 202 Accepted
Location: /queue/12345

202 Accepted告诉客户端,请求已经接受,但还没有处理,可以去Location字段查询进展。

除了上面的头信息,服务器的回应如果有数据体,可以返回一些有效信息(比如任务完成的估计时间、当前状态等等)。

三、查询进展

过了一段时间,客户端就发出请求,查询异步处理的进展。

GET http://api.service.io/queue/12345 

服务器回应 200。

HTTP/1.1 200 Ok  

<response>
 <status>PENDING</status>
  <eta>2 mins.</eta>
  <link rel="cancel" method="delete" href="/queue/12345" /> 
</response>

200 Ok告诉客户端,请求成功,具体情况查看数据体。数据体里给出提示,异步操作已成功或还需要等待。

四、异步操作成功

有一种特殊情况,用户查询异步操作的进展的时候,可能会希望,如果异步操作已经完成,就直接跳转到新资源。

这时,服务器回应 303。

HTTP/1.1 303 See Other 
Location: /stars/97865

303 see other告诉客户端,重定向到不同的资源。Location字段就是跳转的目标,也就是新资源的网址。

五、删除查询链接

一旦异步操作完成,客户端可以要求服务器删除查询链接。

DELETE http://api.service.io/queue/12345 

服务器回应 204。

HTTP/1.1 204 No Content

204 No Content告诉客户端,删除成功。以后,客户端再访问这个查询链接,服务器回应404 Not Found。

如果客户端不删除查询链接,服务器完成异步任务后,也可以自动删除。客户端再请求这个链接,服务器回应410 Gone,表示该链接永久性不再可用。

(完)

文档信息

原文链接: http://www.ruanyifeng.com/blog/2018/12/async-api-design.html

0     0

评价列表(0)

返回首页