restfulapi設(shè)計(jì)原則和規(guī)范方案(完整版)
【正文】 e表示返回類型。注：Microsoft,PayPal等公司也已經(jīng)引入Swagger 來定義自己的REST API 文檔。閱讀和學(xué)習(xí)是一種非常好的習(xí)慣，堅(jiān)持下去，讓我們共同進(jìn)步。通過Swagger進(jìn)行REST API的正確定義，用戶可以理解遠(yuǎn)程服務(wù)并使用最少實(shí)現(xiàn)邏輯與遠(yuǎn)程服務(wù)進(jìn)行交互。比如，會(huì)得到這樣一個(gè)文檔。? 406 Not Acceptable [GET]：用戶請(qǐng)求的格式不可得（比如用戶請(qǐng)求JSON格式，但是只有XML格式）。②為了將總數(shù)發(fā)給客戶端，使用訂制的HTTP頭： XTotalCount.狀態(tài)碼（Status Codes）服務(wù)器向用戶返回的狀態(tài)碼和提示信息，常見的有以下一些（方括號(hào)中是該狀態(tài)碼對(duì)應(yīng)的HTTP動(dòng)詞）。下面是一些常見的參數(shù)。還有兩個(gè)不常用的HTTP動(dòng)詞。舉例：/cars 而不是 /car/users 而不是 /user/products 而不是 /product/settings 而不是 /setting使用子資源表達(dá)關(guān)系。舉例來說，某個(gè)URL是/cards/show/1，其中show是動(dòng)詞，這個(gè)URL就設(shè)計(jì)錯(cuò)了，正確的寫法應(yīng)該是/cards/1，然后用GET方法表示show。另一種做法是，將版本號(hào)放在HTTP頭信息中，但不如放入U(xiǎn)RL方便和直觀。使用的是標(biāo)準(zhǔn)的 HTTP 方法，Http標(biāo)準(zhǔn)中定義的最主要四個(gè)動(dòng)詞：GET、POST、PUT、DELETE。本文即將描述的，即是創(chuàng)建RESTful架構(gòu)的API所要遵循的原則與規(guī)范。如果一個(gè)架構(gòu)符合REST原則，就稱它為RESTful架構(gòu)。客戶端與服務(wù)器互動(dòng)的過程，通常涉及到服務(wù)器端數(shù)據(jù)和狀態(tài)的變化過程，比如文件被修改，訪問數(shù)量增加等。版本(Versioning)應(yīng)該將API的版本號(hào)放入U(xiǎn)RL。具體細(xì)則：使用名詞而不是動(dòng)詞。不要混淆名詞單數(shù)和復(fù)數(shù)，為了保持簡單，只對(duì)所有資源使用復(fù)數(shù)。? DELETE（DELETE）：從服務(wù)器刪除資源。為集合提供過濾、排序、選擇和分頁等功能。比如，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的注：①移動(dòng)端能夠顯示其中一些字段，它們其實(shí)不需要一個(gè)資源的所有字段，給API消費(fèi)者一個(gè)選擇字段的能力，這會(huì)降低網(wǎng)絡(luò)流量，提高API可用性。? 404 NOT FOUND [*]：用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄，服務(wù)器沒有進(jìn)行操作，該操作是冪等的。? GET /collection：返回資源對(duì)象的列表（數(shù)組）? GET /collection/resource：返回單個(gè)資源對(duì)象? POST /collection：返回新生成的資源對(duì)象? PUT /collection/resource：返回完整的資源對(duì)象? PATCH /collection/resource：返回完整的資源對(duì)象? DELETE /collection/resource：返回一個(gè)空文檔使用HATEOAS的Hypermedia APIRESTful API最好使用Hypermedia as the Engine of Application State（超媒體作為應(yīng)用狀態(tài)的引擎），即返回結(jié)果中提供鏈接，連向其他API方法，超文本鏈接可以建立更好的文本瀏覽，使得用戶不查文檔，也知道下一步應(yīng)該做什么。Swagger規(guī)范定義了一組描述一個(gè)API所需的文件格式，類似于描述Web服務(wù)的WSDL。閱讀過后，希望您提出保貴的意見或建議。Swagger API可以使用YAML或JSON來表示。1認(rèn)證（Authentication）API的身份認(rèn)證盡量使用OAuth 。? 500 INTERNAL SERVER ERROR [*]：服務(wù)器發(fā)生錯(cuò)誤，用戶將無法判斷發(fā)出的請(qǐng)求是否成功。? 202 Accepted [*]：表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）? 204 NO CONTENT [DELETE]：用戶刪除數(shù)據(jù)成功。perSize=100：指定第幾頁，以及每頁的記錄數(shù)。注：Get方法和查詢參數(shù)不應(yīng)該涉及狀態(tài)改變。常用的HTTP動(dòng)詞有下面五個(gè)：? GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。正確的寫法是把動(dòng)詞transfer改成名詞transaction，資源不能是動(dòng)詞，但是可以是一種服務(wù)：POST /transaction?from=1amp。使得API版本變得強(qiáng)制性，不要發(fā)布無版本的API，使用簡單數(shù)字。二、RESTful API應(yīng)遵循的原則協(xié)議(Protocol)API與用戶的通信協(xié)議，盡量使用HTTPs協(xié)議。? 資源（resource）：網(wǎng)絡(luò)上的一個(gè)實(shí)體或者說是一個(gè)具體信息，可以是一段文本、一張圖片、一首歌曲、一種服務(wù)。 RE
公司管理相關(guān)推薦
鄂ICP備17016276號(hào)-1