當前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

[译] RESTful API 设计最佳实践

發布時間：2023/12/3 编程问答 23 豆豆

生活随笔收集整理的這篇文章主要介紹了 [译] RESTful API 设计最佳实践小編覺得挺不錯的,現在分享給大家,幫大家做個參考.

https://juejin.im/entry/6844903503953920007

?

[譯] RESTful API 設計最佳實踐

閱讀 8779

2017-10-16

原文鏈接：?segmentfault.com

原文：RESTful API Design. Best Practices in a Nutshell.
作者：Philipp Hauer

項目資源的URL應該如何設計？用名詞復數還是用名詞單數？一個資源需要多少個URL？用哪種HTTP方法來創建一個新的資源？可選參數應該放在哪里？那些不涉及資源操作的URL呢？實現分頁和版本控制的最好方法是什么？因為有太多的疑問，設計RESTful API變得很棘手。在這篇文章中，我們來看一下RESTful API設計，并給出一個最佳實踐方案。

每個資源使用兩個URL

資源集合用一個URL，具體某個資源用一個URL：

/employees #資源集合的URL /employees/56 #具體某個資源的URL

用名詞代替動詞表示資源

這讓你的API更簡潔，URL數目更少。不要這么設計：

/getAllEmployees /getAllExternalEmployees /createEmployee /updateEmployee

更好的設計：

GET /employees GET /employees?state=external POST /employees PUT /employees/56

用HTTP方法操作資源

使用URL指定你要用的資源。使用HTTP方法來指定怎么處理這個資源。使用四種HTTP方法POST，GET，PUT，DELETE可以提供CRUD功能（創建，獲取，更新，刪除）。

獲取：使用GET方法獲取資源。GET請求從不改變資源的狀態。無副作用。GET方法是冪等的。GET方法具有只讀的含義。因此，你可以完美的使用緩存。
創建：使用POST創建新的資源。
更新：使用PUT更新現有資源。
刪除：使用DELETE刪除現有資源。

2個URL乘以4個HTTP方法就是一組很好的功能。看看這個表格：

?POST（創建）GET（讀取）PUT（更新）DELETE（刪除）

/employees	創建一個新員工	列出所有員工	批量更新員工信息	刪除所有員工
/employees/56	（錯誤）	獲取56號員工的信息	更新56號員工的信息	刪除56號員工

對資源集合的URL使用POST方法，創建新資源

創建一個新資源的時，客戶端與服務器是怎么交互的呢？

在資源集合URL上使用POST來創建新的資源過程：

客戶端向資源集合URL/employees發送POST請求。HTTP body 包含新資源的屬性 “Albert Stark”。

RESTful Web服務器為新員工生成ID，在其內部模型中創建員工，并向客戶端發送響應。這個響應的HTTP頭部包含一個Location字段，指示創建資源可訪問的URL。

對具體資源的URL使用PUT方法，來更新資源

使用PUT更新已有資源：

客戶端向具體資源的URL發送PUT請求/employee/21。請求的HTTP body中包含要更新的屬性值（21號員工的新名稱“Bruce Wayne”）。

REST服務器更新ID為21的員工名稱，并使用HTTP狀態碼200表示更改成功。

對可選的、復雜的參數，使用查詢字符串（？）。

不推薦做法：

GET /employees GET /externalEmployees GET /internalEmployees GET /internalAndSeniorEmployees

為了讓你的URL更小、更簡潔。為資源設置一個基本URL，將可選的、復雜的參數用查詢字符串表示。

GET /employees?state=internal&maturity=senior

使用HTTP狀態碼

RESTful Web服務應使用合適的HTTP狀態碼來響應客戶端請求

2xx - 成功 - 一切都很好
4xx - 客戶端錯誤 - 如果客戶端發生錯誤（例如客戶端發送無效請求或未被授權）
5xx – 服務器錯誤 - 如果服務器發生錯誤（例如，嘗試處理請求時出錯）
參考維基百科上的HTTP狀態代碼。但是，其中的大部分HTTP狀態碼都不會被用到，只會用其中的一小部分。通常會用到一下幾個：

2xx：成功3xx：重定向4xx：客戶端錯誤5xx：服務器錯誤

200 成功	301 永久重定向	400 錯誤請求	500 內部服務器錯誤
201 創建	304 資源未修改	401未授權	?
?	?	403 禁止	?
?	?	404 未找到	?

返回有用的錯誤提示

除了合適的狀態碼之外，還應該在HTTP響應正文中提供有用的錯誤提示和詳細的描述。這是一個例子。請求：

GET /employees?state=super

響應：

// 400 Bad Request {"message": "You submitted an invalid state. Valid state values are 'internal' or 'external'","errorCode": 352,"additionalInformation" : "http://www.domain.com/rest/errorcode/352" }

使用小駝峰命名法

使用小駝峰命名法作為屬性標識符。

{?"yearOfBirth":?1982?}

不要使用下劃線（year_of_birth）或大駝峰命名法（YearOfBirth）。通常，RESTful Web服務將被JavaScript編寫的客戶端使用。客戶端會將JSON響應轉換為JavaScript對象（通過調用var person = JSON.parse(response)），然后調用其屬性。因此，最好遵循JavaScript代碼通用規范。
對比：

person.year_of_birth // 不推薦，違反JavaScript代碼通用規范 person.YearOfBirth // 不推薦，JavaScript構造方法命名 person.yearOfBirth // 推薦

在URL中強制加入版本號

從始至終，都使用版本號發布您的RESTful API。將版本號放在URL中以是必需的。如果您有不兼容和破壞性的更改，版本號將讓你能更容易的發布API。發布新API時，只需在增加版本號中的數字。這樣的話，客戶端可以自如的遷移到新API，不會因調用完全不同的新API而陷入困境。使用直觀的 “v” 前綴來表示后面的數字是版本號。

/v1/employees

你不需要使用次級版本號（“v1.2”），因為你不應該頻繁的去發布API版本。

提供分頁信息

一次性返回數據庫所有資源不是一個好主意。因此，需要提供分頁機制。通常使用數據庫中眾所周知的參數offset和limit。

/employees?offset=30&limit=15?#返回30?到?45的員工

如果客戶端沒有傳這些參數，則應使用默認值。通常默認值是offset = 0和limit = 10。如果數據庫檢索很慢，應當減小limit值。

/employees #返回0?到?10的員工

此外，如果您使用分頁，客戶端需要知道資源總數。例：請求：

GET?/employees

響應：

{"offset": 0,"limit": 10,"total": 3465,"employees": [//...] }

非資源請求用動詞

有時API調用并不涉及資源（如計算，翻譯或轉換）。例：

GET /translate?from=de_DE&to=en_US&text=Hallo GET /calculate?para2=23&para2=432

在這種情況下，API響應不會返回任何資源。而是執行一個操作并將結果返回給客戶端。因此，您應該在URL中使用動詞而不是名詞，來清楚的區分資源請求和非資源請求。

考慮特定資源搜索和跨資源搜索

提供對特定資源的搜索很容易。只需使用相應的資源集合URL，并將搜索字符串附加到查詢參數中即可。

GET /employees?query=Paul

如果要對所有資源提供全局搜索，則需要用其他方法。前文提到，對于非資源請求URL，使用動詞而不是名詞。因此，您的搜索網址可能如下所示：

GET /search?query=Paul?//返回 employees, customers, suppliers 等等.

在響應參數中添加瀏覽其它API的鏈接

理想情況下，不會讓客戶端自己構造使用REST API的URL。讓我們思考一個例子。
客戶端想要訪問員工的薪酬表。為此，他必須知道他可以通過在員工URL（例如/employees/21/salaryStatements）中附加字符串“salaryStatements”來訪問薪酬表。這個字符串連接很容易出錯，且難以維護。如果你更改了訪問薪水表的REST API的方式（例如變成了/employees/21/salary-statement或/employees/21/paySlips），所有客戶端都將中斷。
更好的方案是在響應參數中添加一個links字段，讓客戶端可以自動變更。
請求：

GET?/employees/

響應：

//...{"id":1,"name":"Paul","links": [{"rel": "salary","href": "/employees/1/salaryStatements"}]}, //...

如果客戶端完全依靠links中的字段獲得薪資表，你更改了API，客戶端將始終獲得一個有效的URL（只要你更改了link字段，請求的URL會自動更改），不會中斷。另一個好處是，你的API變得可以自我描述，需要寫的文檔更少。
在分頁時，您還可以添加獲取下一頁或上一頁的鏈接示例。只需提供適當的偏移和限制的鏈接示例。

GET /employees?offset=20&limit=10 {"offset": 20,"limit": 10,"total": 3465,"employees": [//...],"links": [{"rel": "nextPage","href": "/employees?offset=30&limit=10"},{"rel": "previousPage","href": "/employees?offset=10&limit=10"}] }

總結

以上是生活随笔為你收集整理的[译] RESTful API 设计最佳实践的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。

API
RESTful

上一篇：苹果电脑系统可以玩lol吗(苹果电脑系统
下一篇： centos安装docker显示 No

生活随笔