异步 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，表示该链接永久性不再可用。