REST API設計規範

這裡整理的rest api的設計規範，注意和後端開發的api介面文件做一下區分，不是乙個概念。api是rest api的超集，rest api 是api的子集；所有的rest api都是api，但不是所有的api都是rest api

api通常使用https協議，確保互動資料的傳輸安全，網域名稱盡量將api部署在專用網域名稱下https：，具體公共要求如下

1.在uri中使用小寫字母，不要採用駝峰命名。

方便時，在uri路徑中應始終首選小寫字母。

2.使用名詞來表示資源

uri只包含只能包含名詞較好，應該引用作為事物（名詞）的資源，而不是引用動作（動詞）

3.使用正斜槓（/）表示層次關係，uri結尾不要帶正斜槓（/）

http:/device-management/managed-devices//scripts/4.使用連字元（-）來提高uri的可讀性，不要使用下劃線（_）

下劃線（_）字元可能會被部分遮擋或在某些瀏覽器或螢幕中完全隱藏。

//可讀性強 //更多容易出錯

http://install_script_location

5.不要在uri中使用crud函式名稱

uri不應用於指示執行crud功能。uri應該用於唯一標識資源，而不是對資源進行任何操作。應該使用http請求方法來指示執行了哪個crud功能。

http get http:/device-management/managed-devices //獲取所有裝置 http post http:/device-management/managed-devices //建立新裝置 http get http:/device-management/managed-devices/ //獲取給定id的裝置 http put http:/device-management/managed-devices/ //更新給定id的裝置

http delete http:/device-management/managed-devices/ //刪除給定id的裝置

6.杜絕完全不規範的縮寫，盡量見明知意避免望文生義

7.不要使用副檔名

如果要使用副檔名突出顯示api的**型別，則應依靠通過content-type標頭傳達的**型別來確定如何處理正文內容。

//錯誤示範 //這是正確的uri

http:/device-management/managed-devices

通過對"資源"操作(讀、寫、通知)的依賴實現業務領域之間的依賴。api作為"業務領域"間溝通的手段，應該以面向資源角度進行命名。

1.單個資源：可以是乙個單體或集合

例如，customers是集合資源，customer是單例資源。我們可以customers使用uri/customers來標識集合資源。我們可以customer使用uri「/customers/」來標識單個資源。

個人建議當api**為跨源sql或者跨庫關聯可以用集合，單個表或者庫可以用單體模式。

2.子資源

根據公司現狀可以和業務或者需求確定好大的分類，確定2-4級分類

2.1.業務域方面

主資源名稱根據業務域進行劃分（具體的和抽象的），子資源可附加業務需求、物件。子資源需要逐級索引命名，

（1）具體的資料物件：

（2）抽象的物件概念：

2.2渠道方面

（1）內部

inner

user

（2）外部

pc customer

store

3.版本控制

如果後期公司涉及到版本更新可以再最初或者第二次開始新增版本引數，將版本號放在url中或者header中 v1，v2，vn…

目前引數支援：integer,number,boolean,string

api契約應該由」api名 + 入參」共同組成，引數動詞和名詞可做一下統一規範

條目 item 特性 feature 金額 amount

。。。

很多時候，您會遇到需求，其中您將需要根據某些資源屬性對資源進行排序，過濾或限制的集合。為此，請勿建立新的api，而應在資源收集api中啟用排序，過濾和分頁功能，並將輸入引數作為查詢引數傳遞。例如

http:/device-management/managed-devices?region=美國

http:/device-management/managed-devices?region=usa&brand=xyz

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 - [*]：伺服器發生錯誤，使用者將無法判斷發出的請求是否成功。

其它補充：

（1）過濾資訊：？limit=10 ？offset=10 ？page=1 ？sortby=name （3）驗證：確定使用者是其宣告的身份，比如提供賬戶的密碼

（4）授權：保證使用者有對資源特定操作的許可權。比如使用者私人資訊只能自己能夠訪問，其他人無法看到，有些特殊的操作只能管理員可以操作，其他使用者有唯讀的許可權等

restful api 設計指南

正確甄別api、rest api、restful api和web service之間的異同

rest api教程

REST API設計規範

軟體定義網路基礎 REST API的設計規範

UI設計規範

硬體設計規範

REST API設計規範

軟體定義網路基礎 REST API的設計規範

UI設計規範

硬體設計規範

相關推薦