restful 是目前最流行的 api 設計規範，用於 web 資料介面的設計。
它的大原則容易把握，但是細節不容易做對。本文總結 restful 的設計細節，介紹如何設計出易於理解和使用的 api。
url 設計
1.1 動詞 + 賓語
restful 的核心思想就是，客戶端發出的資料操作指令都是"動詞 + 賓語"的結構。比如，get /articles這個命令，get是動詞，/articles是賓語。
動詞通常就是五種 http 方法，對應 crud 操作。
get：讀取（read）
post：新建（create）
put：更新（update）
patch：更新（update），通常是部分更新
delete：刪除（delete）
根據 http 規範，動詞一律大寫。
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮（手機、平板、桌面電腦、其他專用裝置......）。
因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現"api first"的設計思想。restful api是目前比較成熟的一套網際網路應用程式的api設計理論。
1. 什麼是rest
rest全稱是representational state transfer，中文意思是表述（編者注：通常譯為表徵）性狀態轉移。 它首次出現在2023年roy fielding的博士**中，roy fielding是http規範的主要編寫者之一。 他在**中提到："我這篇文章的寫作目的，就是想在符合架構原理的前提下，理解和評估以網路為基礎的應用軟體的架構設計，得到乙個功能強、效能好、適宜通訊的架構。rest指的是一組架構約束條件和原則。" 如果乙個架構符合rest的約束條件和原則，我們就稱它為restful架構。
rest本身並沒有創造新的技術、元件或服務，而隱藏在restful背後的理念就是使用web的現有特徵和能力， 更好地使用現有web標準中的一些準則和約束。雖然rest本身受web技術的影響很深， 但是理論上rest架構風格並不是繫結在http上，只不過目前http是唯一與rest相關的例項。 所以我們這裡描述的rest也是通過http實現的rest。
什麼是restful架構：
每乙個uri代表一種資源；
客戶端和伺服器之間，傳遞這種資源的某種表現層；
客戶端通過四個http動詞（get/post/put/delete），對伺服器端資源進行操作，實現」表現層狀態轉化」。
uri要讓乙個資源可以被識別，需要有個唯一標識，在web中這個唯一標識就是uri(uniform resource identifier)。 uri既可以看成是資源的位址，也可以看成是資源的名稱。如果某些資訊沒有使用uri來表示，那它就不能算是乙個資源， 只能算是資源的一些資訊而已。uri的設計應該遵循可定址性原則，具有自描述性，需要在形式上給人以直覺上的關聯。
http動詞
1. 使用get、post、put、delete這幾種請求模式
請求模式也可以說是動作、資料傳輸方式，通常我們在web中的form有get、post兩種，而在http中，存在下發這幾種。
get (選擇)：從伺服器上獲取乙個具體的資源或者乙個資源列表。
post （建立）： 在伺服器上建立乙個新的資源。
put（更新）：以整體的方式更新伺服器上的乙個資源。
patch （更新）：只更新伺服器上乙個資源的乙個屬性。
delete（刪除）：刪除伺服器上的乙個資源。
今天，我將介紹restful api的設計細節，**如何設計一套合理、好用的api,
它要考慮這些方面：協議，網域名稱，版本，路徑，http，過濾，狀態碼，錯誤處理，返回結果json, 身份認證等
api與使用者的通訊協議，總是使用https協議。
應該盡量將api部署在專用網域名稱之下。
如果確定api很簡單，不會有進一步擴充套件，可以考慮放在主網域名稱下。
應該將api的版本號放入url。
另一種做法是，將版本號放在http頭資訊中，但不如放入url方便和直觀。github採用這種做法。/v1/
路徑又稱"終點"（endpoint），表示api的具體**。
在restful架構中，每個**代表一種資源（resource），所以**中不能有動詞，只能有名詞，而且所用的名詞往往與資料庫的**名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），所以api中的名詞也應該使用複數。
舉例來說，有乙個api提供動物園（zoo）的資訊，還包括各種動物和雇員的資訊，則它的路徑應該設計成下面這樣。
對於資源的具體操作型別，由http動詞表示。常用的http動詞有下面五個（括號裡是對應的sql命令）。
還有兩個不常用的http動詞。 下面是一些例子。 如果記錄數量很多，伺服器不可能都將它們返回給使用者。api應該提供引數，過濾返回結果。下面是一些常見的引數。
引數的設計允許存在冗餘，即允許api路徑和url引數偶爾有重複。比如，get /zoo/id/animals 與 get /animals?zoo_id=id 的含義是相同的。伺服器向使用者返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的http動詞）。
狀態碼的完全列表參見這裡。如果狀態碼是4xx，就應該向使用者返回出錯資訊。一般來說，返回的資訊中將error作為鍵名，出錯資訊作為鍵值即可。
針對不同操作，伺服器向使用者返回的結果應該符合以下規範。 比如，當使用者向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的身份認證應該使用oauth2.0框架。
（2）伺服器返回的資料格式，應該盡量使用json，避免使用xml。
oauth在"客戶端"與"服務提供商"之間，設定了乙個授權層（authorization layer）。"客戶端"不能直接登入"服務提供商"，只能登入授權層，以此將使用者與客戶端區分開來。"客戶端"登入授權層所用的令牌（token），與使用者的密碼不同。使用者可以在登入的時候，指定授權層令牌的許可權範圍和有效期。
"客戶端"登入授權層以後，"服務提供商"根據令牌的許可權範圍和有效期，向"客戶端"開放使用者儲存的資料。
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置 因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...
RESTful API 設計指南
原文 網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致 api 構架的流行，甚至出現 api first 的設計思想。restful api 是目前比較成熟的一套網際網...