restful api 設計總結
@(技術-架構)[api, 規範, 設計]
restful的介面設計風格應用的越來越廣泛，包括spring cloud等微服務架構平台之間的呼叫都是以restful設計風格為主，但是很多程式猿依然是停留在表面的理解上，沒有深刻的去理解使用restful風格規範，同時在設計restful介面的時候是有很多細節需要思考，以下就是個人對restful介面的深入理解以及總結。
1、協議&網域名稱&版本
協議：api與使用者的通訊協議，總是使用https協議。
網域名稱：可以部署專有網域名稱或者是主網域名稱下加入url裡面。
版本：應該將api的版本號放入url。
2、curd的請求設計
rest的關鍵原則把api分解成一種邏輯上的資源。這些資源可以通過有具體含義的http方法（get, post, put, patch, delete）來進行修改。
get/users - 獲取user列表① 新增：新增物件一般用到的是post方法。get/users/12 - 獲取指定id為12的user物件
post/users - 建立乙個新的user
put/users/12 - 更新id為12的user
patch/users/12 - 對id為12的user進行部分更新
delete/users/12 - 刪除id為12的user
post/users - 建立乙個新的user② 刪除：delete作為刪除的方法post/users?count=4 - 批量建立user物件
delete/users/12 - 刪除id為12的user③ 更新：put、patch都是作為更新的http方法，put表示更新user物件，patch是對物件部分更新delete/users [134 , 232 , 223 , 442] - 批量刪除id為134 , 232 , 223 , 442的user
put/users/12 - 更新id為12的user④ 查詢：get一般作為查詢的http方法，如何優雅的滿足複雜的介面，不是一件很值得**的事情。put/users - 批量更新user
patch/users/12 - 對id為12的user進行部分更新
patch/users - 批量對user進行部分更新
查詢單個物件
get/users/12 - 獲取指定id為12的user物件
查詢多個物件
get/users - 獲取user列表
條件過濾與分頁查詢
get/users?page=3&page_count=30：指定第幾頁，以及每頁的記錄數。查詢多個物件時，一般返回物件的列表，當分頁查詢需要返回查詢的總的資料，應當在響應頭部裡面加入x-total-count的引數，同時在頭部加入x-page和x-page-size引數。get/users?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
get/users?role_id=1：指定篩選條件
x-total-count：1023x-page：3
x-page-size：30
複雜的查詢條件當我們使用高階搜尋的時候，get方法的引數長度是沒法滿足查詢的需求，這時候我們可以用post方法提交引數實體來實現需求。
post/users/search?page=3&page_count=304、hypermedia api
restful api最好做到hypermedia，即返回結果中提供鏈結，連向其他api方法，使得使用者不查文件，也知道下一步應該做什麼。
比如，當使用者向api.github.com的根目錄發出請求，會得到這樣乙個文件。
上面**表示，文件中有乙個link屬性，使用者讀取這個屬性就知道下一步該呼叫什麼api了。rel表示這個api與當前**的關係（collection關係，並給出該collection的**），href表示api的路徑，title表示api的標題，type表示返回型別。
hypermedia api的設計被稱為hateoas。github的api就是這種設計，訪問api.github.com會得到乙個所有可用api的**列表。
從上面可以看到，如果想獲取當前使用者的資訊，應該去訪問api.github.com/user，然後就得到了下面結果。
上面**表示，伺服器給出了提示資訊，以及文件的**。
RESTful API 設計指南總結
rest 英文 representational state transfer，簡稱rest 描述了乙個架構樣式的網路系統，比如 web 應用程式。它首次出現在 2000 年 roy fielding 的博士 中，他是 http 規範的主要編寫者之一。在目前主流的三種web服務互動方案中，rest相...
簡單總結restful API 設計規範
restful的核心思想就是，客戶端發出的資料 操作指令都是 動詞 賓語 的結構，比如get articles這個命令，get是動詞，articles是賓語，動詞通常就有5種http請求方法，對應crud操作，根據 http 規範，動詞一律大寫。get 讀取 read post 新建 create ...
RESTful API 設計指南
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置 因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致api構架的流行，甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...