restful規(guī)范
GET /tickets?- 獲取 tickets 列表
GET /tickets/12?- 獲取一個單獨的 ticket
POST /tickets?- 創(chuàng)建一個新的 ticket
PUT /tickets/12?- 更新 ticket #12
DELETE /tickets/12?- 刪除 ticket #12
GET /collection：返回資源對象的列表（數(shù)組）
GET /collection/resource：返回單個資源對象
POST /collection：返回新生成的資源對象
PUT /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔
接入點的名稱應該選擇單數(shù)還是復數(shù)呢？keep-it-simple原則可以在此應用。雖然你內(nèi)在的語法知識會告訴你用復數(shù)形式描述單一資源實例是錯誤的，但實用主義的答案是保持URL格式一致并且始終使用復數(shù)形式。不用處理各種奇形怪狀的復數(shù)形式（比如person/people，goose/geese）可以讓API消費者的生活更加美好，也讓API提供者更容易實現(xiàn)API（因為大多數(shù)現(xiàn)代框架天然地將/tickets和/tickets/12放在同一個控制器下處理）。
但是你該如何處理（資源的）關(guān)系呢？如果關(guān)系依托于另外一個資源，Restful原則提供了很好的指導原則。讓我們來看一個例子。一個ticket包含許多消息（message）。這些消息邏輯上與/tickets接入點的映射關(guān)系如下：
GET /tickets/12/messages - 獲取ticket #12下的消息列表
GET /tickets/12/messages/5 - 獲取ticket #12下的編號為5的消息
POST /tickets/12/messages - 為ticket #12創(chuàng)建一個新消息
PUT /tickets/12/messages/5 - 更新ticket #12下的編號為5的消息
PATCH /tickets/12/messages/5 - 部分更新ticket #12下的編號為5的消息
DELETE /tickets/12/messages/5 - 刪除ticket #12下的編號為5的消息
應該將API的版本號放入URL。
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
結(jié)果過濾，排序和搜索
最好是盡量保持基本資源URL的簡潔性。?復雜結(jié)果過濾器、排序需求和高級搜索 (當限定在單一類型的資源時) ，都能夠作為在基本URL之上的查詢參數(shù)來輕松實現(xiàn)。下面讓我們更詳細的看一下:
過濾: 對每一個字段使用一個唯一查詢參數(shù)，就可以實現(xiàn)過濾。?例如，當通過“/tickets”終端來請求一個票據(jù)列表時，你可能想要限定只要那些在售的票。這可以通過一個像?GET /tickets?state=open 這樣的請求來實現(xiàn)。這里“state”是一個實現(xiàn)了過濾功能的查詢參數(shù)。
排序: 跟過濾類似, 一個泛型參數(shù)排序可以被用來描述排序的規(guī)則. 為適應復雜排序需求，讓排序參數(shù)采取逗號分隔的字段列表的形式，每一個字段前都可能有一個負號來表示按降序排序。我們看幾個例子:
GET /tickets?sort=-priority?- 獲取票據(jù)列表，按優(yōu)先級字段降序排序
GET /tickets?sort=-priority,created_at?-?獲取票據(jù)列表，按“priority”字段降序排序。在一個特定的優(yōu)先級內(nèi)，較早的票排在前面。
搜索: 有時基本的過濾不能滿足需求，這時你就需要全文檢索的力量?；蛟S你已經(jīng)在使用?ElasticSearch或者其它基于?Lucene的搜索技術(shù)。當全文檢索被用作獲取某種特定資源的資源實例的機制時， 它可以被暴露在API中，作為資源終端的查詢參數(shù)，我們叫它“q”。搜索類查詢應當被直接交給搜索引擎，并且API的產(chǎn)出物應當具有同樣的格式，以一個普通列表作為結(jié)果。
把這些組合在一起，我們可以創(chuàng)建以下一些查詢:
GET /tickets?sort=-updated_at?- 獲取最近更新的票
GET /tickets?state=closed&sort=-updated_at?- 獲取最近更新并且狀態(tài)為關(guān)閉的票。
GET /tickets?q=return&state=open&sort=-priority,created_at?- 獲取優(yōu)先級最高、最先創(chuàng)建的、狀態(tài)為開放的票，并且票上有 'return' 字樣。
一般查詢的別名
為了使普通用戶的API使用體驗更加愉快， 考慮把條件集合包裝進容易訪問的RESTful?路徑中。比如上面的，最近關(guān)閉的票的查詢可以被包裝成GET /tickets/recently_closed
限制哪些字段由API返回
API的使用者并不總是需要一個資源的完整表示。選擇返回字段的功能由來已久，它使得API使用者能夠最小化網(wǎng)絡(luò)阻塞，并加速他們對API的調(diào)用。
使用一個字段查詢參數(shù)，它包含一個用逗號隔開的字段列表。例如，下列請求獲得的信息將剛剛足夠展示一個在售票的有序列表:
GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at
更新和創(chuàng)建應該返回一個資源描述
一個 PUT, POST 或者 PATCH 調(diào)用可能會對指定資源的某些字段造成更改，而這些字段本不在提供的參數(shù)之列 (例如: created_at 或 updated_at 這兩個時間戳)。 為了防止API使用者為了獲取更新后的資源而再次調(diào)用該API，應當使API把更新(或創(chuàng)建)后的資源作為response的一部分來返回。
以一個產(chǎn)生創(chuàng)建活動的 POST 操作為例, 使用一個HTTP 201 狀態(tài)代碼然后包含一個Location header來指向新生資源的URL。
200 OK - [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。
202 Accepted - [*]：表示一個請求已經(jīng)進入后臺排隊（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤，服務(wù)器沒有進行新建或修改數(shù)據(jù)的操作，該操作是冪等的。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌、用戶名、密碼錯誤）。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對），但是訪問是被禁止的。
404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄，服務(wù)器沒有進行操作，該操作是冪等的。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當創(chuàng)建一個對象時，發(fā)生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯誤，用戶將無法判斷發(fā)出的請求是否成功。
無效數(shù)據(jù)不返回，必要數(shù)據(jù)返回
什么叫無效數(shù)據(jù)不返回，必要數(shù)據(jù)返回呢？
無效數(shù)據(jù)清理：對于json響應接口，我們需要遵守對所有值為null的字段不做返回，對前端不關(guān)心的數(shù)據(jù)不做返回（合理的定義VO是很有必要的）。?
對于spring boot 我們可以用下配置，實現(xiàn)字段值為null時不做返回。
spring.jackson.date-format=yyyy-MM-ddHH:mm:ss
spring.jackson.time-zone=Asia/Shanghai
spring.jackson.default-property-inclusion=non_null
必要數(shù)據(jù)返回：對于添加（POST）、修改（PUT | PATCH）這類方法我們需要立即返回添加或更新后的數(shù)據(jù)以備前端使用（這是一個約定需要遵守）。
關(guān)于RESTFul API設(shè)計時，URL路徑中不可以使用下劃線嗎
如果網(wǎng)站的鏈接包含hello-world，搜索引擎收錄的索引為hello 和 world；
如果網(wǎng)站的鏈接包含hello_world，搜索引擎收錄的索引為hello_world。
參考資料? ?Best Practices for Designing a Pragmatic RESTful API? ? ?
? ? ? ? ? ? ? ??中文對照
? ? ? ? ? ? ? ??RESTful API 設(shè)計指南
? ? ? ? ? ? ? GitHub API
