RESTful-API設(shè)計原則與規(guī)范

1、RESTful-API設(shè)計原則與規(guī)范34445錯誤！未定義書簽。錯誤！未定義書簽。錯誤！未定義書簽。8910101111RESTfulAPI設(shè)計原則與規(guī)范一、背景與基礎(chǔ)概念2、 RESTfulAPI應(yīng)遵循的原則1 、協(xié)議(Protocol)2 、域名(ROOTURL)3 、版本(Versioning)4 、路徑(Endpoints)5 、HTTP動詞(HTTPVerbs)6 、過濾信息(Filtering)7 、狀態(tài)碼(StatusCodes)8 、錯誤處理(Errorhandling)9 、返回結(jié)果(Response)10 、使用HATEOAS的HypermediaAPI11 、認(rèn)證(Aut

2、hentication)3、 SwaggerAPI標(biāo)準(zhǔn)REST,即RepresentationalStateTransfe的縮寫。RESTful架構(gòu)，是目前最流行的一種互聯(lián)網(wǎng)軟件架構(gòu)。它結(jié)構(gòu)清晰、符合標(biāo)準(zhǔn)、易于理解、擴展方便，基于這個風(fēng)格設(shè)計的軟件可以更簡潔，更有層次，更易于實現(xiàn)緩存等機制，所以正得到越來越多網(wǎng)站的采用。如果一個架構(gòu)符合REST原則，就稱它為RESTful架構(gòu)。本文即將描述的，即是創(chuàng)建RESTful架構(gòu)的API所要遵循的原則與規(guī)范。一、背景與基礎(chǔ)概念Web應(yīng)用程序最重要的REST原則是，客戶端和服務(wù)器之間的交互在請求之間是無狀態(tài)的。從客戶端到服務(wù)器的每個請求都必須包含理解請求所

3、必需的信息。?資源(resource:網(wǎng)絡(luò)上的一個實體或者說是一個具體信息，可以是一段文本、一張圖片、一首歌曲、一種服務(wù)。?統(tǒng)一資源定位符(URI,UniversalResourceIdentifier:一個資源的識別符或者說是一個地址，通過URI你可以定位到特定的資源。要獲取這個資源，需要訪問它的URI，因此，URI就成了每一個資源的地址或獨一無二的識別符。?狀態(tài)轉(zhuǎn)換(StateTransfe)r:所有資源都共享統(tǒng)一的接口，以便在客戶端和服務(wù)器之間傳輸狀態(tài)?？蛻舳伺c服務(wù)器互動的過程，通常涉及到服務(wù)器端數(shù)據(jù)和狀態(tài)的變化過程，比如文件被修改，訪問數(shù)量增加等。使用的是標(biāo)準(zhǔn)的HTTP方法，Http標(biāo)

4、準(zhǔn)中定義的最主要四個動詞：GET、POST、PUT、DELETE。它們分別對應(yīng)四種基本操作：- GET：用來獲取資源- POST：用來新建資源- PUT：用來更新資源- DELETE：用來刪除資源?Hypermedia是應(yīng)用程序狀態(tài)的引擎，資源表示通過超鏈接互聯(lián)。二、RESTfulAPI應(yīng)遵循的原則1 、協(xié)議(Protocol)API與用戶的通信協(xié)議，盡量使用HTTPs協(xié)議。HTTPs協(xié)議的所有信息都是加密傳播，第三方無法竊聽，具有校驗機制，一旦被篡改，通信雙方會立刻發(fā)現(xiàn)，配備身份證書，防止身份被冒充。2 、域名(ROOTURL)應(yīng)該盡量將API部署在專用域名之下。如果確定API很簡單，不會有

5、進一步擴展，可以考慮放在主域名下。/api/3 、版本(Versioning)應(yīng)該將API的版本號放入URL。另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github采用這種做法。注：需要注意版本規(guī)劃，以便以后API的升級和維護。使得API版本變得強制性，不要發(fā)布無版本的API，使用簡單數(shù)字，避免小數(shù)點如2.5。4、路徑(Endpoints)路徑表示API的具體網(wǎng)址URL。在RESTful架構(gòu)中，每個URL代表一種資源(resource),所以網(wǎng)址中不能有動詞，只能有名詞，而且所用的名詞往往與代表的對象名稱對應(yīng)。一般來說，某一同種

6、記錄的“集合“(collection),所以API中的名詞也應(yīng)該使用復(fù)數(shù)。具體細(xì)則：1使用名詞而不是動詞。舉例來說，某個URL是/cards/show/1,其中show是動詞，這個URL就設(shè)計錯了，正確的寫法應(yīng)該是/cards/1,然后用GET方法表示show。如果某些動作是HTTP動詞表示不了的，你就應(yīng)該把動作做成一種資源。比如網(wǎng)上匯款，從賬戶1向賬戶2匯款500元，錯誤的URI是：POST/accounts/1/transfer/500/to/2o正確的寫法是把動詞transfer改成名詞transaction,資源不能是動詞，但是可以是一種服務(wù)：POST/transaclion?froi

7、n-l&lo=2&amoun1=500.00。2、使用復(fù)數(shù)名詞。不要混淆名詞單數(shù)和復(fù)數(shù)，為了保持簡單，只對所有資源使用復(fù)數(shù)。舉例：/cars而不是/car/users而不是/user/products而不是/product/settings而不是/setting3、使用子資源表達(dá)關(guān)系。如果一個資源與另外一個資源有關(guān)系，使用子資源。舉例：GET/cars/911/drivers/返回car911的所有司機GET/cars/911/drivers/8返回car911的8號司機5、HTTP動詞(HTTPVerbs)對于資源的具體操作類型，由HTTP動詞表示。常用的HTTP動詞有下面五

8、個； GET(SELECT)：從服務(wù)器取出資源(一項或多項)。 POST(CREATE)：在服務(wù)器新建一個資源。 PUT(UPDATE)：在服務(wù)器更新資源(客戶端提供改變后的完整資源)。 PATCH(UPDATE)：在服務(wù)器更新資源(客戶端提供改變的屬性)。 DELETE(DELETE)：從服務(wù)器刪除資源。還有兩個不常用的HTTP動詞。 HEAD：獲取資源的元數(shù)據(jù)。 OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的。注：Get方法和查詢參數(shù)不應(yīng)該涉及狀態(tài)改變。使用PUT,POST和DELETE方法而不是GET方法來改變狀態(tài)。6、過濾信息(Filtering)如果記錄數(shù)量很多，服務(wù)

9、器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)，過濾返回結(jié)果。為集合提供過濾、排序、選擇和分頁等功能。下面是一些常見的參數(shù)。 ?limit=10：指定返回記錄的數(shù)量?offset=10：指定返回記錄的開始位置?pageNumber=2&perSize=10Q指定第幾頁，以及每頁的記錄數(shù)。?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序。1 ?animal_type_id=1：指定篩選條件參數(shù)的設(shè)計允許存在冗余，即允許API路徑和URL參數(shù)偶爾有重復(fù)。比如，GET/zoo/ID/animals與GET/animals?zoo_id=ID的含

10、義是相同的注：移動端能夠顯示其中一些字段，它們其實不需要一個資源的所有字段，給API消費者一個選擇字段的能力，這會降低網(wǎng)絡(luò)流量，提高API可用性。為了將總數(shù)發(fā)給客戶端，使用訂制的HTTP頭：X-Total-Count.7 、狀態(tài)碼（StatusCodes）服務(wù)器向用戶返回的狀態(tài)碼和提示信息，常見的有以下一些（方括號中是該狀態(tài)碼對應(yīng)的HTTP動詞）。?200OK-GET：服務(wù)器成功返回用戶請求的數(shù)據(jù)，該操作是冪等的（Idempotent）。?201CREATED-POST/PUT/PATCH：用戶新建或修改數(shù)據(jù)成功。?202Accepted-*：表示一個請求已經(jīng)進入后臺排隊（異步任務(wù)）?204N

11、OCONTENT-DELETE：用戶刪除數(shù)據(jù)成功。?400INVALIDREQUEST-POST/PUT/PATCH：用戶發(fā)出的請求有錯誤，服務(wù)器沒有進行新建或修改數(shù)據(jù)的操作，該操作是冪等的。?401Unauthorized-*：表示用戶沒有權(quán)限（令牌、用戶名、密碼錯誤）。?403Forbidden-*：表示用戶得到授權(quán)（與401錯誤相對），但是訪問是被禁止的。?404NOTFOUND-*：用戶發(fā)出的請求針對的是不存在的記錄，服務(wù)器沒有進行操作，該操作是冪等的。?406NotAcceptable-GET:用戶請求的格式不可得（比如用戶請求JSON格式,但是只有XML格式）。?410Gone-G

12、ET：用戶請求的資源被永久刪除，且不會再得到的。?422Unprocesableentity-POST/PUT/PATCH：當(dāng)創(chuàng)建一個對象時，發(fā)生一個驗證錯誤。?500INTERNALSERVERERROR-*：服務(wù)器發(fā)生錯誤，用戶將無法判斷發(fā)出的請求是否成功。8 、錯誤處理（Errorhandling）如果狀態(tài)碼是4xx，就應(yīng)該向用戶返回出錯信息。盡量使用詳細(xì)的錯誤包裝信息："errors":"userMessage":"Sorry,therequestedresourcedoesnotexist","internalMe

13、ssage":"Nocarfoundinthedatabase","code":4xx,"moreinfo":"9 、返回結(jié)果（Response）服務(wù)器返回的數(shù)據(jù)格式，應(yīng)該盡量使用JSON,避免使用XML。針對不同操作，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范。?GET/collection：返回資源對象的列表（數(shù)組）?GET/collection/resource：返回單個資源對象?POST/collection：返回新生成的資源對象?PUT/collection/resource：返回完整的資源對象?PATCH/

14、collection/resource：返回完整的資源對象?DELETE/collection/resource：返回一個空文檔10 、使用HATEOAS的HypermediaAPIRESTfulAPI最好使用HypermediaastheEngineofApplicationState（超媒體作為應(yīng)用狀態(tài)的引擎），即返回結(jié)果中提供鏈接，連向其他API方法，超文本鏈接可以建立更好的文本瀏覽，使得用戶不查文檔，也知道下一步應(yīng)該做什么。比如，當(dāng)用戶向的根目錄發(fā)出請求，會得到這樣一個文檔。"link":"rel":"collection"h

15、ref":""title":"Listofzoos","type":"application/vnd.yourformat+json"上面代碼表示，文檔中有一個link屬性，用戶讀取這個屬性就知道下一步該調(diào)用什么API了。rel表示這個API與當(dāng)前網(wǎng)址的關(guān)系(collection關(guān)系，并給出該collection的網(wǎng)址)，href表示API的路徑，title表示API的標(biāo)題，type表示返回類型。11 、認(rèn)證(Authentication)API的身份認(rèn)證盡量使用OAuth2.0框架。三、Swa

16、ggerAPI標(biāo)準(zhǔn)API的文檔管理和信息描述，將使用Swagge進行。Swagge層一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。Swagge的目標(biāo)是對RESTAPI定義一個標(biāo)準(zhǔn)的和語言無關(guān)的接口，可讓人和計算機無需訪問源碼、文檔或網(wǎng)絡(luò)流量監(jiān)測就可以發(fā)現(xiàn)和理解服務(wù)的能力。Swagge規(guī)范定義了一組描述一個API所需的文件格式，類似于描述Web服務(wù)的WSDL。通過Swagge進彳fRESTAPI的正確定義，用戶可以理解遠(yuǎn)程服務(wù)并使用最少實現(xiàn)邏輯與遠(yuǎn)程服務(wù)進行交互。與為底層編程所實現(xiàn)的接口類似，Swagge消除了調(diào)用服務(wù)時可能會有的猜測。注：Microsoft,

17、PayPal等公司也已經(jīng)引入Swagger來定義自己的RESTAPI文檔。SwaggerAPI可以使用YAML或JSON來表示。Swagger®類API文檔工具可以滿足下列需求：?支持API自動生成同步的在線文檔?這些文檔可用于項目內(nèi)部API審核?方便測試人員了解API?這些文檔可作為客戶產(chǎn)品文檔的一部分進行發(fā)布?支持API規(guī)范生成代碼，生成的客戶端和服務(wù)器端骨架代碼可以加速開發(fā)和測試速度通常情況下，API的Swagger®述為JSON文件，也可使用YAML描述的文件。附Swagge戌:件示例："swagger":"2.0",&quo

18、t;info":"version":"1.0.0","title":"SwaggerPetstore(Simple)","description":"AsampleAPIthatusesapetstoreasanexampletodemonstratefeaturesintheswagger-2.0specification","termsOfService":""contact":"name":

19、"SwaggerAPIteam","email":"foo","url":"http:/swagger.io","license":"name":"MIT","url":"/licenses/MIT","host":"petstore.swagger.io","basePath":"/ap

20、i","schemes":"http","consumes":"application/json","produces":"application/json","paths":"/pets":": "Returns all pets from the system that the": "findPets","get":"descriptionus

21、erhasaccessto","operationId"produces":"application/json","application/xml","text/xml","text/html","parameters":"name":"tags","in":"query","description":"tagstofilterby",&

22、quot;required":false,"type":"array","items":"type":"string","collectionFormat":"csv","name":"limit","in":"query","description":"maximumnumberofresultstoreturn","

23、;required":false,"type":"integer","format":"int32",200":"description":"petresponse","schema":"type":"array","items":"$ref":"#/definitions/pet","default":"d

24、escription":"unexpectederror","schema":"$ref":"#/definitions/errorModel","post":"description":"Createsanewpetinthestore.Duplicatesareallowed","operationId":"addPet","produces":"application/j

25、son","parameters":"name":"pet","in":"body","description":"Pettoaddtothestore","required":true,"schema":"$ref":"#/definitions/newPet","responses":"200":"descript

26、ion":"petresponse","schema":"$ref":"#/definitions/pet","description":"unexpectederror","schema":"$ref":"#/definitions/errorModel","/pets/id":"get":"description":"Returnsa

27、userbasedonasingleID,iftheuserdoesnothaveaccesstothepet","operationId":"findPetById","produces":"application/json","application/xml","text/xml","text/html","parameters":"name":"id","in"

28、:"path","description":"IDofpettofetch","required":true,"type":"integer","format":"int64","responses":"200":"description":"petresponse","schema":"$ref":"#/d

29、efinitions/pet","default":"description":"unexpectederror","schema":"$ref":"#/definitions/errorModel","delete":"description":"deletesasinglepetbasedontheIDsupplied","operationId":"deletePet&q

30、uot;,"parameters":"name":"id","in":"path","description":"IDofpettodelete","required":true,"type":"integer","format":"int64","responses":"204":"description":"petdeleted","default":"description":"unexpectederror","schema":"$ref":"#/definitions/errorModel","defini