RESTful API 實踐

dayday_up 發布于2019-08-15 10:56 / 3307人閱讀

摘要：實現與它們所提供的服務是解耦的，這促進了獨立的可進化性。正確的情況返回與響應碼，在錯誤的情況下他們通常返回或。示例用于刪除由標識的資源。成功刪除返回及響應正文或沒有正文響應。客戶不存在，不合法資源命名一切在工藝軟件開發的命名是成功的關鍵。

什么是 REST?

REST 即表述性狀態傳遞（英文：Representational State Transfer，簡稱REST）是Roy Fielding博士在2000年他的博士論文中提出來的一種軟件架構風格（http://www.ics.uci.edu/~field...）。它是一種針對網絡應用的設計和開發方式，可以降低開發的復雜性，提高系統的可伸縮性。

六個約束：

統一接口（Uniform Interface）

無狀態（Stateless）

緩存（Cacheable）

客戶-服務器（Client-Server）

分層系統（Layered System）

按需代碼（Code on Demand）

統一接口（Uniform Interface）

使REST 架構風格區別于其他基于網絡的架構風格的核心特征是，它強調組件之間要有一個統一的接口。通過在組件接口上應用通用性的軟件工程原則，整體的系統架構得到了簡化，交互的可見性也得到了改善。實現與它們所提供的服務是解耦的，這促進了獨立的可進化性。然而，付出的代價是，統一接口降低了效率，因為信息都使用標準化的形式來轉移，而不能使用特定于應用的需求的形式。REST 接口被設計為可以高效地轉移大粒度的超媒體數據，并針對Web的常見情況做了優化，但是這也導致了該接口對于其他形式的架構交互并不是最優的。

無狀態（Stateless）

通信必須在本質上是無狀態的，因此從客戶到服務器的每個請求都必須包含理解該請求所必需的所有信息，不能利用任何存儲在服務器上的上下文，會話狀態因此要全部保存在客戶端。

緩存（Cacheable）

為了改善網絡的效率。緩存約束要求一個請求的響應中的數據被隱式地或顯式地標記為可緩存的或不可緩存的。如果響應是可緩存的，那么客戶端緩存就可以為以后的相同請求重用這個響應的數據。

客戶-服務器（Client-Server）

通過分離用戶接口和數據存儲這兩個關注點，我們改善了用戶接口跨多個平臺的可移植性；同時通過簡化服務器組件，改善了系統的可伸縮性。然而，對于 Web來說，最重要的是這種關注點的分離允許組件獨立地進化，從而支持多個組織領域的Internet規模的需求。

分層系統（Layered System）

分層系統風格通過限制組件的行為（即，每個組件只能“看到”與其交互的緊鄰層），將架構分解為若干等級的層。通過將組件對系統的知識限制在單一層內，為整個系統的復雜性設置了邊界，并且提高了底層獨立性。我們能夠使用層來封裝遺留的服務，使新的服務免受遺留客戶端的影響，通過將不常用的功能轉移到一個共享的中間組件中，從而簡化組件的實現。中間組件還能夠通過支持跨多個網絡和處理器的負載均衡，來改善系統的可伸縮性。

按需代碼（Code on Demand）

通過減少必須被預先實現的功能的數目，簡化了客戶端的開發。允許在部署之后下載功能代碼也改善了系統的可擴展性。然而，這也降低了可見性，因此它只是 REST 的一個可選的約束。

HTTP 動作 GET

HTTP GET 用于檢索（讀取）資源。正確的情況返回JSON與200 HTTP響應碼，在錯誤的情況下他們通常返回404(NOT FOUND)或400(BAD REQUEST)。

示例

GET http://www.example.com/custom...
GET http://www.example.com/custom...
GET http://www.example.com/bucket...

通過GET它應該永遠不會修改服務器上的任何資源。

POST

HTTP POST 通常用于創建資源。正確的情況返回201 HTTP響應碼及Location header（資源 URI）。

示例

POST http://www.example.com/customers
POST http://www.example.com/custom...

PUT

HTTP PUT 通常用于更新資源。將請求正文內容替換已知資源的原始數據。

示例

PUT http://www.example.com/custom...
PUT http://www.example.com/custom...

DELETE

HTTP DELETE 用于刪除由URI標識的資源。成功刪除返回200 HTTP及響應正文或沒有正文響應204 HTTP(NO CONTENT)。

示例

DELETE http://www.example.com/custom...
DELETE http://www.example.com/custom...
DELETE http://www.example.com/bucket...

下表是 URI 結合 HTTP METHOD 建議的返回值

HTTP Verb(Method)	/customers	/customers/{id}
GET	200 (OK)。客戶列表，數據量大可使用分頁排序篩選	200 (OK)。單個客戶。404 (Not Found) ID客戶不存在，400 (BAD REQUEST) ID不合法
POST	201 (Created)，"Location" header 為 /customers/{id} 包含新的資源ID	404 (Not Found)
PUT	404 (Not Found)	200 (OK)或者204 (No Content)。404 (Not Found) ID客戶不存在，400 (BAD REQUEST) ID不合法
DELETE	404 (Not Found)	200 (OK)或者204 (No Content)。404 (Not Found) ID客戶不存在，400 (BAD REQUEST) ID不合法

資源命名

一切在工藝軟件開發的命名是成功的關鍵。

除了適當的應用 HTTP Verb(Method)，資源命名可以說是最受爭議和最重要的概念。當資源被命名好時，API 是直觀和易于使用的。做得太差，同樣的 API 能感覺太表面化和難以使用和理解。下面是一些提示，讓你去當創建資源 URI 為您新的 API。

資源 URI 應使用名詞而不是動詞命名。一個 RESTful URI 應該指一種資源，而不是采取行動。名詞具有屬性而動詞沒有。

服務套件中每個資源至少有一個 URI 標識它。URI 應遵循一種可預見，分層結構，以增加可理解性，從而提高可用性。

在一個訂單系統與客戶、訂單、行項目的資源設計：

創建一個新的客戶
POST http://www.example.com/customers

讀取客戶 ID 為 33245
GET http://www.example.com/custom...
相同的 URI 將用于更新(PUT)與刪除(DELETE)客戶

這里為產品設計的 URI:
POST http://www.example.com/products
創建一個新的產品

GET|PUT|DELETE http://www.example.com/produc...
讀取、更新、刪除 ID 為 66432 的產品為

現在變得很有趣，我們如何為客戶創建新的訂單？
一種選擇是
POST http://www.example.com/orders
毫無疑問它是可以工作的，但它卻在客戶的上下文之外

下面的 URI 更清晰
POST http://www.example.com/custom...
現在我們知道這個訂單是為客戶 33245 創建的

獲取 33245 客戶訂單使用如下 URI
GET http://www.example.com/custom...
現在，我們繼續來看分層的 URI 設計。如下：
POST http://www.example.com/custom...
這會將行項目添加到訂單 #8769(這是客戶 #33245)，獲取該 URI 資源會返回訂單下所有的行項目，如果行項目毫無意義或者在客戶的上下文以外的地方能感覺到我們會提供這樣一個 URI
POST www.example.com/orders/8769/lineitems

看看一些廣泛使用的 API 來得到資源命名竅門和利用你的隊友來完善您的 API 資源。

Twitter: https://dev.twitter.com/docs/api

Facebook: http://developers.facebook.co...

LinkedIn: https://developer.linkedin.co...

GitHub: https://developer.github.com/v3/

Response Body 簡單響應

示例

{
   "url":"https://api.github.com/gists/20c98223d9b59e1d48e5",
   "id":"1",
   "description":"description of gist",
   "public":true,
   "user":{
       "login":"octocat",
       "id":1,
       "avatar_url":"https://github.com/images/error/octocat_happy.gif",
       "gravatar_id":"somehexcode",
       "url":"https://api.github.com/users/octocat"
   },
   "comments":0,
   "comments_url":"https://api.github.com/gists/19d18b30e8af75090307/comments/",
   "html_url":"https://gist.github.com/1",
   "git_pull_url":"git://gist.github.com/1.git",
   "git_push_url":"git@gist.github.com:1.git",
   "created_at":"2010-04-14T02:15:15Z"
}

分頁響應

total_count 總記錄數

items 數據項

示例

{
   "total_count":40,
   "items":[
       {
           "id":3081286,
           "name":"Tetris",
           "full_name":"dtrupenn/Tetris",
           "owner":{
               "login":"dtrupenn",
               "id":872147,
               "type":"User"
           },
           "private":false,
           "html_url":"https://github.com/dtrupenn/Tetris",
           "description":"A C implementation of Tetris using Pennsim through LC4",
           "fork":false,
           "url":"https://api.github.com/repos/dtrupenn/Tetris",
           "created_at":"2012-01-01T00:31:50Z",
           "updated_at":"2013-01-05T17:58:47Z",
           "pushed_at":"2012-01-01T00:37:02Z"
       }
   ]
}

錯誤響應

code 錯誤碼

message 錯誤信息

示例
{
   "code": 12345,
   "message": "錯誤描述"
}

參考資源

http://www.restapitutorial.com/
https://www.oschina.net/trans...

GPU云服務器云服務器 restful_api返回 api設計的最佳實踐 RESTful RESTful框架

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/67438.html

RESTful實踐（具體應用）思考

摘要：其他交互一般會遵循一些數據結構協議或者狀態值，比如不同的操作結果對應不同的狀態值，且出錯會返回指定的錯誤信息方便前端進行提示等。 RESTful這種架構已經具有很長的時間和歷程了，但似乎最近restful這個詞出現的頻率特別高，目前不是很清楚是因為我自個兒現在是以restful風格寫程序產生的孕婦效應，還是單頁面程序開發的流行造成的。其實一開始我也是不想寫這篇文章的，因為網絡上與re...

myshell 2019-06-28 13:49 評論0 收藏0
4.3 路由設計/RESTful API-博客后端Api-NodeJs+Express+Mysql實

摘要：路由設計路由設計以用戶注冊為例介紹如何閉環用戶注冊開發注意點使用郵箱注冊驗證郵箱是否注冊目前真實開發業務大部分都是手機號注冊，這塊由于沒有購買短信服務首先，在文件夾下新建上圖中對應真實業務邏輯現附上業務實現代碼加密國際化工具類用戶服務路由設計路由設計以用戶注冊為例介紹如何閉環用戶注冊開發注意點：（1）使用郵箱注冊（2）驗證郵箱是否注冊【目前真實開發業務大部分都是手機號注冊，這塊...

1fe1se 2019-08-23 17:16 評論0 收藏0
PHP / Laravel API 開發推薦閱讀清單

showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社區優秀文章 Laravel 5.5+passport 放棄 dingo 開發 API 實戰，讓 API 開發更省心 - 自造車輪。 API 文檔神器 Swagger 介紹及在 PHP 項目中使用 - API 文檔撰寫方案推薦 Laravel API 項目必須使用的 8 個...

shmily 2019-06-28 18:34 評論0 收藏0
Node.js+MongoDB對于RestfulApi中用戶token認證實踐

摘要：則是目前比較成熟的一套互聯網應用程序的設計理論。則允許操作，不一樣，報錯返回或者加入黑名單。再看下我們的數據庫中的用戶信息，值也被存入了進來，便于我們之后進行權限驗證。訪問同時將我們的值在中以傳入正確獲得用戶名則表示我們訪問請求通過了驗證。 showImg(https://segmentfault.com/img/remote/1460000008629635?w=800&h=534)...

robin 2019-08-21 11:34 評論0 收藏0
Node.js+MongoDB對于RestfulApi中用戶token認證實踐

摘要：則是目前比較成熟的一套互聯網應用程序的設計理論。則允許操作，不一樣，報錯返回或者加入黑名單。再看下我們的數據庫中的用戶信息，值也被存入了進來，便于我們之后進行權限驗證。訪問同時將我們的值在中以傳入正確獲得用戶名則表示我們訪問請求通過了驗證。 showImg(https://segmentfault.com/img/remote/1460000008629635?w=800&h=534)...

klinson 2019-06-26 17:11 評論0 收藏0
人人都是 API 設計師：我對 RESTful API、GraphQL、RPC API 的思考

摘要：通常情況下，偽都是基于第一層次與第二層次設計的。為了解決這個版本不兼容問題，在設計的一種實用的做法是使用版本號。例如，建議第三位版本號通常表示兼容升級，只有不兼容時才需要變更服務版本。原文地址：梁桂釗的博客博客地址：blog.720ui.com 歡迎關注公眾號：「服務端思維」。一群同頻者，一起成長，一起精進，打破認知的局限性。有一段時間沒怎么寫文章了，今天提筆寫一篇自己對 API 設...

ormsf 2019-05-23 16:27 評論0 收藏0