原文：
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮（手機、平板、桌面電腦、其他專用裝置......）。
因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致 api 構架的流行，甚至出現"api first"的設計思想。restful api 是目前比較成熟的一套網際網路應用程式的 api 設計理論。我以前寫過一篇《理解 restful 架構》，**如何理解這個概念。
今天，我將介紹 restful api 的設計細節，**如何設計一套合理、好用的 api。我的主要參考資料是這篇《principles of good restful api design》。
一、協議
api 與使用者的通訊協議，總是使用 https 協議。
二、網域名稱
應該盡量將 api 部署在專用網域名稱之下。
如果確定 api 很簡單，不會有進一步擴充套件，可以考慮放在主網域名稱下。
三、版本（versioning）
應該將 api 的版本號放入 url。
另一種做法是，將版本號放在 http 頭資訊中，但不如放入 url 方便和直觀。
四、路徑（endpoint）
路徑又稱"終點"（endpoint），表示 api 的具體**。
在 restful 架構中，每個**代表一種資源（resource），所以**中不能有動詞，只能有名詞，而且所用的名詞往往與資料庫的**名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），所以 api 中的名詞也應該使用複數。
舉例來說，有乙個 api 提供動物園（zoo）的資訊，還包括各種動物和雇員的資訊，則它的路徑應該設計成下面這樣。
五、http 動詞
對於資源的具體操作型別，由 http 動詞表示。
常用的 http 動詞有下面五個（括號裡是對應的 sql 命令）。
get（select）：從伺服器取出資源（一項或多項）。還有兩個不常用的 http 動詞。post（create）：在伺服器新建乙個資源。
put（update）：在伺服器更新資源（客戶端提供改變後的完整資源）。
patch（update）：在伺服器更新資源（客戶端提供改變的屬性）。
delete（delete）：從伺服器刪除資源。
head：獲取資源的元資料。下面是一些例子。options：獲取資訊，關於資源的哪些屬性是客戶端可以改變的。
get /zoos：列出所有動物園六、過濾資訊（filtering）post /zoos：新建乙個動物園
get /zoos/id：獲取某個指定動物園的資訊
put /zoos/id：更新某個指定動物園的資訊（提供該動物園的全部資訊）
patch /zoos/id：更新某個指定動物園的資訊（提供該動物園的部分資訊）
delete /zoos/id：刪除某個動物園
get /zoos/id/animals：列出某個指定動物園的所有動物
delete /zoos/id/animals/id：刪除某個指定動物園的指定動物
如果記錄數量很多，伺服器不可能都將它們返回給使用者。api 應該提供引數，過濾返回結果。
下面是一些常見的引數。
?limit=10：指定返回記錄的數量引數的設計允許存在冗餘，即允許 api 路徑和 url 引數偶爾有重複。比如，get /zoo/id/animals 與 get /animals?zoo_id=id 的含義是相同的。?offset=10：指定返回記錄的開始位置。
?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
?animal
typeid=1：指定篩選條件
七、狀態碼（status codes）
伺服器向使用者返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的 http 動詞）。
200 ok - [get]：伺服器成功返回使用者請求的資料，該操作是冪等的（idempotent）。狀態碼的完全列表參見這裡。201 created - [post/put/patch]：使用者新建或修改資料成功。
204 no content - [delete]：使用者刪除資料成功。
400 invalid request - [post/put/patch]：使用者發出的請求有錯誤，伺服器沒有進行新建或修改資料的操作，該操作是冪等的。。
404 not found - [*]：使用者發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是冪等的。
500 internal server error - [*]：伺服器發生錯誤，使用者將無法判斷發出的請求是否成功。
八、返回結果
針對不同操作，伺服器向使用者返回的結果應該符合以下規範。
get /collection：返回資源物件的列表（陣列）九、hypermedia apiget /collection/resource：返回單個資源物件
post /collection：返回新生成的資源物件
put /collection/resource：返回完整的資源物件
patch /collection/resource：返回完整的資源物件
delete /collection/resource：返回乙個空文件
restful api 最好做到 hypermedia，即返回結果中提供鏈結，連向其他 api 方法，使得使用者不查文件，也知道下一步應該做什麼。
比如，當使用者向 api.example.com 的根目錄發出請求，會得到這樣乙個文件。
}上面**表示，文件中有乙個 link 屬性，使用者讀取這個屬性就知道下一步該呼叫什麼 api 了。rel 表示這個 api 與當前**的關係（collection 關係，並給出該 collection 的**），href 表示 api 的路徑，title 表示 api 的標題，type 表示返回型別。
hypermedia api 的設計被稱為 hateoas。github 的 api 就是這種設計，訪問api.github.com 會得到乙個所有可用 api 的**列表。
從上面可以看到，如果想獲取當前使用者的資訊，應該去訪問 api.github.com/user，然後就得到了下面結果。 上面**表示，伺服器給出了提示資訊，以及文件的**。十、其他
（1）api 的身份認證應該使用 oauth 2.0框架。
（2）伺服器返回的資料格式，應該盡量使用 json，避免使用 xml。
（完）
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置 因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...