設計良好的Web API

最近由於工作的關係，需要設計API提供給User使用，我們採用的是HTTP + RESTful + JSON Response的方式，剛好和近期讀到的一篇文章所建議的方法相同，在這邊稍微記錄一下。

這篇文章是：Designing robust web API

根據作者過去的經驗，提供幾個在設計API的Best Practice或個人經驗。分別為：

• Use a RESTful Model：使用HTTP + RESTful + JSON作為API的開發架構
• Stabilize your API：Expose the API as minimal as possible. 保持API的穩健，不應該有大量變動。已經釋出的功能很難被刪減。
• Version your API：在API的Request URL中加入版本資訊方便使用者做區別。
• Asynchronous Invocation：如果你的response需要很長的時間，採用asyn的方法。實作上有兩種模式可以參考：(1) Client在request之後，server response是一個receipt，用來向server詢問response是否已經處理完畢。(2) Client提供callback address，當server處理完response之後，會丟回callback的位置讓client接收。

【相關閱讀】

Designing robust web API