rest api
REST(Representational State Transfer, 表述性狀態轉移)。
REST是一種架構風格，不是一種協議或者技術。
RESTful API 翻譯過來就是REST式的API就是滿足REST這種風格的API。具有跨平台、跨語言的優勢，並且實現簡潔直觀。近來越來越受開發者喜歡，特別是最近微服務化的火熱又推動了一把REST的使用。
REST實現方式
基於即有的HTTP/HTTPS + URI + XML/JSON實現。在REST架構風格中，對象被抽象成一種資源（使用清晰的名詞來定義）。
REST的資源是通過HTTP協議定義的動詞（GET/PUT/POST/DELETE等）來操作，並使用URI來唯一標識某個資源公布出來的接口。
REST資源定位
REST使用URI實現資源定位，即對外提供的接口就是一系列的URI及其參數。
在設計RESTful API時資源地址的設計一定要非常嚴謹，如果設計不好不僅REST接口的風格無法統一，系統的擴展性和易用性也會大打折扣。
資源地址
一個典型的URI包括協議名稱、主機名、服務端口、資源地址和查詢字符串5部分組成。
schema://host:port/path?queryString
| 組成 | 說明 |
|---|---|
| schema | 協議名稱。一般是HTTP/HTTPS |
| host | 主機名，可以是域名或者ip |
| port | 端口號 |
| path | 資源地址, 使用/分隔邏輯上的層次結構 |
| ？ | 分隔資源地址和查詢字符串，如果沒有查詢字符串，？可省略 |
| queryString | 查詢字符串，key=value形式，如果有多個可以使用&連接 |
常用於資源URI中的標點符號
為了增加邏輯的清晰性，在路徑變量中提供了幾個常用的標點符號：
?(問號)：用來分隔資源地址和查詢字符串，這個上一節有說明。&(與)：用來分隔多個查詢條件的參數，這個上一節有說明。,(逗號)：用來分隔邏輯上有次序的作用域信息，使用"月,日,年"-(連接符)：可以做為邏輯上的輔助分隔，例如2012-2018表示2012年到2018年。_(下划線)：一般用於多個單詞的連接成一個完整的字段，例如book_type_id=1;(分號)：用來分隔無次序的作用域信息，例如並列查詢條件。
常用的資源地址示例：
| 功能 | 資源地址 |
|---|---|
| 添加/創建 | POST /books |
PUT /books/{id} |
|
| 刪除 | DELETE /books/{id} |
| 修改/更新 | PUT /books/{id} |
| 查詢全部 | GET /books |
| 主鍵查詢 | GET /books/{id} |
GET /books?id=12345 |
|
| 分頁作用域查詢 | GET /books?start=0&size=10 |
GET /books/01,2012-12,2014 |
|
GET /books/restful;program=java;type=web |
|
GET /books?limit=100&sort=bookname |
API接口版本
任何人設計的有用的功能都是要向前演進的，不可能一成不變。一般是引入版本號的概念來解決這種演進的問題。而RESTful API的版本號可以通過以下幾種方式實現：
- 在uri中放版本信息：GET /v1/users/1
- Accept Header：Accept: application/json+v1
- 自定義 Header：X-Api-Version: 1
通常建議使用第一種方式，簡單直觀。
其他
- RESTful API最好做到Hypermedia，即返回結果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應該做什么
- 請求以及返回數據使用JSON格式，不要使用XML格式
- 返回出錯信息時，數據key統一起來，使用使用
ERROR，而錯誤信息作為value