目錄二、restful api設計指南
rest這個詞，是[roy thomas fielding在他2023年的博士**中提出的。
fielding將他對網際網路軟體的架構原則，定名為rest，即representational state transfer的縮寫。翻譯是"表現層狀態轉化"。
如果乙個架構符合rest原則，就稱它為restful架構。
rest的名稱"表現層狀態轉化"中，省略了主語。"表現層"其實指的是"資源"（resources）的"表現層"。
資源就是網路上的乙個實體，或者說是網路上的具體資訊。
uri：uniform resource identifier，統一資源識別符號
url：uniform resource location統一資源定位符
uri只代表資源實體，不代表表現形式，有些****最後的.html是不需要的，因為這個字尾名屬於表示格式，屬於表現層。而uri應該只代表資源的位置，他的具體表現形式應該在http請求頭資訊中用acept和content—type欄位指定，這兩個欄位才是對「表現層的描述」。
http協議是乙個無狀態協議，這意味著，所有的狀態都儲存在伺服器。如果客戶端想要操作伺服器，必須通過某種手段，讓伺服器端發生"狀態轉化"（state transfer）。而這種轉化是建立在表現層之上的，所以就是"表現層狀態轉化"。
客戶端只能通過http協議發生這種改變。具體來說，就是http協議裡面，四個表示操作方式的動詞：get、post、put、delete。它們分別對應四種基本操作：get用來獲取資源，post用來新建資源（也可以用於更新資源），put用來更新資源，delete用來刪除資源。
api與使用者的通訊協議，總是使用https協議
盡量部署在專用的網域名稱之下，就是給api專門做乙個伺服器。
/v1/在restful架構中，每個**代表一種資源（resource），所以**中不能有動詞，只能有名詞，而且所用的名詞往往與資料庫的**名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），所以api中的名詞也應該使用複數。
舉例來說，有乙個api提供動物園（zoo）的資訊，還包括各種動物和雇員的資訊，則它的路徑應該設計成下面這樣。
/v1/zoos
/v1/animals
/v1/employees
常用的http動詞有下面五個（括號裡是對應的sql命令）。
get（select）：從伺服器取出資源（一項或多項）。
post（create）：在伺服器新建乙個資源。
put（update）：在伺服器更新資源（客戶端提供改變後的完整資源）。
patch（update）：在伺服器更新資源（客戶端提供改變的屬性）。
delete（delete）：從伺服器刪除資源。
get /zoos：列出所有動物園
post /zoos：新建乙個動物園
get /zoos/id：獲取某個指定動物園的資訊
put /zoos/id：更新某個指定動物園的資訊（提供該動物園的全部資訊）
patch /zoos/id：更新某個指定動物園的資訊（提供該動物園的部分資訊）
delete /zoos/id：刪除某個動物園
get /zoos/id/animals：列出某個指定動物園的所有動物
delete /zoos/id/animals/id：刪除某個指定動物園的指定動物
下面是一些常見的引數。
?limit=10：指定返回記錄的數量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件
常見狀態碼：
200 ok - [get]：伺服器成功返回使用者請求的資料，該操作是冪等的（idempotent）。
201 created - [post/put/patch]：使用者新建或修改資料成功。
202 accepted - [*]：表示乙個請求已經進入後台排隊（非同步任務）
204 no content - [delete]：使用者刪除資料成功。
400 invalid request - [post/put/patch]：使用者發出的請求有錯誤，伺服器沒有進行新建或修改資料的操作，該操作是冪等的。
401 unauthorized - [*]：表示使用者沒有許可權（令牌、使用者名稱、密碼錯誤）。
403 forbidden - [*] 表示使用者得到授權（與401錯誤相對），但是訪問是被禁止的。
404 not found - [*]：使用者發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是冪等的。
406 not acceptable - [get]：使用者請求的格式不可得（比如使用者請求json格式，但是只有xml格式）。
410 gone -[get]：使用者請求的資源被永久刪除，且不會再得到的。
422 unprocesable entity - [post/put/patch] 當建立乙個物件時，發生乙個驗證錯誤。
500 internal server error - [*]：伺服器發生錯誤，使用者將無法判斷發出的請求是否成功。
最基本的思路應該是：盡可能提供準確的錯誤資訊，比如資料格式不正確、缺少某個欄位......而不是直接說「請求錯誤」之類的資訊。
如果狀態碼是4xx，就應該向使用者返回出錯資訊。一般來說，返回的資訊中將error作為鍵名，出錯資訊作為鍵值即可。
針對不同操作，伺服器向使用者返回的結果應該符合以下規範。
get /collection：返回資源物件的列表（陣列）
get /collection/resource：返回單個資源物件
post /collection：返回新生成的資源物件
put /collection/resource：返回完整的資源物件
patch /collection/resource：返回完整的資源物件
delete /collection/resource：返回乙個空文件
比如，當使用者向api.example.com的根目錄發出請求，會得到這樣乙個文件。
}hypermedia api的設計被稱為hateoas。github的api就是這種設計，訪問api.github.com會得到乙個所有可用api的**列表。
api一般不能隨意的訪問
驗證：確定使用者是申明的身份，比如提供賬戶的密碼，不然偽造身份是非常危險的
授權：保證使用者對請求資源特定操作的許可權。比如使用者的私人資訊只能自己訪問，其他人無法看到，某些特殊的操作許可權只有管理員有。
如果沒有通過驗證，返回401 unauthorized狀態碼，並在body中說明具體的錯誤資訊；而沒有被授權訪問的資源操作，需要返回403 forbiden狀態碼，還有詳細的錯誤資訊。
github api對某些使用者未被授權訪問的資源操作返回404 not found，目的是為了防止私有資源的洩露，如果返回403的話就等於告訴別人這個是私有資源。
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置 因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...
RESTful API 設計指南
原文 網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致 api 構架的流行，甚至出現 api first 的設計思想。restful api 是目前比較成熟的一套網際網...