異步 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，表示該鏈接永久性不再可用。

（完）

推薦訂閱源