1949啦网--小小 痛苦,是因为能力和欲望不匹配造成的

异步 API 的设计

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

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

一、同步 API

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

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

 POST https://api.service.io/stars  name='Death Star'  

服务器回应 201。

 HTTP/1.1 201 Created Location: /stars/12345 

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

二、异步请求

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

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

 POST https://api.service.io/stars  name='Death Star'  

服务器回应 202。

 HTTP/1.1 202 Accepted Location: /queue/12345 

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

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

三、查询进展

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

 GET https://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 https://api.service.io/queue/12345  

服务器回应 204。

 HTTP/1.1 204 No Content 

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

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

原文链接:https://www.qiquanji.com/post/6864.html

本站声明:网站内容来源于网络,如有侵权,请联系我们,我们将及时处理。

微信扫码关注

更新实时通知

作者:xialibing 分类:网络教程 浏览: