异步 API 的设计

2019-06-10

JiangRen Mr

一、同步 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,表示该链接永久性不再可用。

近期开课hot
logo

Follow Us

linkedinfacebooktwitterinstagramweiboyoutubebilibilitiktokxigua

We Accept

/image/layout/pay-paypal.png/image/layout/pay-visa.png/image/layout/pay-master-card.png/image/layout/pay-stripe.png/image/layout/pay-alipay.png

地址

Level 10b, 144 Edward Street, Brisbane CBD(Headquarter)
Level 8, 11 York st, Wynyard, Sydney CBD
Business Hub, 155 Waymouth St, Adelaide SA 5000

Disclaimer

footer-disclaimerfooter-disclaimer

JR Academy acknowledges Traditional Owners of Country throughout Australia and recognises the continuing connection to lands, waters and communities. We pay our respect to Aboriginal and Torres Strait Islander cultures; and to Elders past and present. Aboriginal and Torres Strait Islander peoples should be aware that this website may contain images or names of people who have since passed away.

匠人学院网站上的所有内容,包括课程材料、徽标和匠人学院网站上提供的信息,均受澳大利亚政府知识产权法的保护。严禁未经授权使用、销售、分发、复制或修改。违规行为可能会导致法律诉讼。通过访问我们的网站,您同意尊重我们的知识产权。 JR Academy Pty Ltd 保留所有权利,包括专利、商标和版权。任何侵权行为都将受到法律追究。查看用户协议

© 2017-2024 JR Academy Pty Ltd. All rights reserved.

ABN 26621887572