restful規(guī)范
GET /tickets?- 獲取 tickets 列表
GET /tickets/12?- 獲取一個單獨(dú)的 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：返回一個空文檔
接入點(diǎn)的名稱應(yīng)該選擇單數(shù)還是復(fù)數(shù)呢？keep-it-simple原則可以在此應(yīng)用槽奕。雖然你內(nèi)在的語法知識會告訴你用復(fù)數(shù)形式描述單一資源實(shí)例是錯誤的，但實(shí)用主義的答案是保持URL格式一致并且始終使用復(fù)數(shù)形式。不用處理各種奇形怪狀的復(fù)數(shù)形式（比如person/people敏储，goose/geese）可以讓API消費(fèi)者的生活更加美好医吊，也讓API提供者更容易實(shí)現(xiàn)API（因?yàn)榇蠖鄶?shù)現(xiàn)代框架天然地將/tickets和/tickets/12放在同一個控制器下處理）民褂。
但是你該如何處理（資源的）關(guān)系呢？如果關(guān)系依托于另外一個資源唱捣，Restful原則提供了很好的指導(dǎo)原則。讓我們來看一個例子网梢。一個ticket包含許多消息（message）震缭。這些消息邏輯上與/tickets接入點(diǎn)的映射關(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的消息
應(yīng)該將API的版本號放入URL。
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
結(jié)果過濾战虏，排序和搜索
最好是盡量保持基本資源URL的簡潔性拣宰。?復(fù)雜結(jié)果過濾器、排序需求和高級搜索 (當(dāng)限定在單一類型的資源時) 烦感，都能夠作為在基本URL之上的查詢參數(shù)來輕松實(shí)現(xiàn)巡社。下面讓我們更詳細(xì)的看一下:
過濾: 對每一個字段使用一個唯一查詢參數(shù)，就可以實(shí)現(xiàn)過濾手趣。?例如重贺，當(dāng)通過“/tickets”終端來請求一個票據(jù)列表時，你可能想要限定只要那些在售的票回懦。這可以通過一個像?GET /tickets?state=open 這樣的請求來實(shí)現(xiàn)气笙。這里“state”是一個實(shí)現(xiàn)了過濾功能的查詢參數(shù)。
排序: 跟過濾類似, 一個泛型參數(shù)排序可以被用來描述排序的規(guī)則. 為適應(yīng)復(fù)雜排序需求怯晕，讓排序參數(shù)采取逗號分隔的字段列表的形式潜圃，每一個字段前都可能有一個負(fù)號來表示按降序排序。我們看幾個例子:
GET /tickets?sort=-priority?- 獲取票據(jù)列表舟茶，按優(yōu)先級字段降序排序
GET /tickets?sort=-priority,created_at?-?獲取票據(jù)列表谭期，按“priority”字段降序排序。在一個特定的優(yōu)先級內(nèi)吧凉，較早的票排在前面隧出。
搜索: 有時基本的過濾不能滿足需求，這時你就需要全文檢索的力量阀捅≌偷桑或許你已經(jīng)在使用?ElasticSearch或者其它基于?Lucene的搜索技術(shù)。當(dāng)全文檢索被用作獲取某種特定資源的資源實(shí)例的機(jī)制時， 它可以被暴露在API中凄诞，作為資源終端的查詢參數(shù)圆雁，我們叫它“q”。搜索類查詢應(yīng)當(dāng)被直接交給搜索引擎帆谍，并且API的產(chǎn)出物應(yīng)當(dāng)具有同樣的格式伪朽，以一個普通列表作為結(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使用體驗(yàn)更加愉快苛吱， 考慮把條件集合包裝進(jìn)容易訪問的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)建應(yīng)該返回一個資源描述
一個 PUT, POST 或者 PATCH 調(diào)用可能會對指定資源的某些字段造成更改挪略，而這些字段本不在提供的參數(shù)之列 (例如: created_at 或 updated_at 這兩個時間戳)。 為了防止API使用者為了獲取更新后的資源而再次調(diào)用該API滔岳，應(yīng)當(dāng)使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)進(jìn)入后臺排隊(duì)（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功刘离。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤室叉，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的硫惕。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌茧痕、用戶名、密碼錯誤）恼除。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對）踪旷，但是訪問是被禁止的。
404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄，服務(wù)器沒有進(jìn)行操作埃脏，該操作是冪等的搪锣。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式秋忙，但是只有XML格式）彩掐。
410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的灰追。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個對象時堵幽，發(fā)生一個驗(yàn)證錯誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯誤弹澎，用戶將無法判斷發(fā)出的請求是否成功朴下。
無效數(shù)據(jù)不返回，必要數(shù)據(jù)返回
什么叫無效數(shù)據(jù)不返回苦蒿，必要數(shù)據(jù)返回呢殴胧？
無效數(shù)據(jù)清理：對于json響應(yīng)接口，我們需要遵守對所有值為null的字段不做返回佩迟，對前端不關(guān)心的數(shù)據(jù)不做返回（合理的定義VO是很有必要的）团滥。?
對于spring boot 我們可以用下配置，實(shí)現(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
