主要包含內(nèi)容

• 協(xié)議，一般使用HTTPS
• 域名，https://api.example.com
• 版本（Versioning），https://api.example.com/v1/
• 終點(diǎn)（Endpoint），表示API的具體網(wǎng)址。https://api.example.com/v1/zoos
• HTTP動(dòng)詞
• 過濾信息（Filtering）
• 狀態(tài)碼（Status Codes）
• 錯(cuò)誤處理（Error handling）
• 返回結(jié)果，應(yīng)該盡量使用JSON
• Hypermedia API

1. 基本要求：面向資源，使用HTTP動(dòng)詞

HTTP動(dòng)詞有下面五個(gè)（括號(hào)里是對(duì)應(yīng)的SQL命令）

• GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
• POST（CREATE）：在服務(wù)器新建一個(gè)資源。
• PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
• PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
• DELETE（DELETE）：從服務(wù)器刪除資源。

還有兩個(gè)不常用的HTTP動(dòng)詞。

• HEAD：獲取資源的元數(shù)據(jù)。
• OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的。

例子

GET /zoos：列出所有動(dòng)物園
POST /zoos：新建一個(gè)動(dòng)物園
GET /zoos/ID：獲取某個(gè)指定動(dòng)物園的信息
PUT /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的全部信息）
PATCH /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的部分信息）
DELETE /zoos/ID：刪除某個(gè)動(dòng)物園
GET /zoos/ID/animals：列出某個(gè)指定動(dòng)物園的所有動(dòng)物
DELETE /zoos/ID/animals/ID：刪除某個(gè)指定動(dòng)物園的指定動(dòng)物

過濾信息

?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數(shù)。
?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件

2.進(jìn)階：Hypermedia API

即返回結(jié)果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應(yīng)該做什么。

例子

PUST /zoos

普通返回

{
  "zoos": "abc"
}

Hypermedia API 返回查找信息的接口：

{
  "zoos": "abc",
  "link": {
    "rel": "infomation", //rel是relationship的意思
    "url": "/zoos/info"
  }
}

即返回結(jié)果中提供鏈接，連向其他API方法

參考
https://zhuanlan.zhihu.com/p/30396391
http://www.ruanyifeng.com/blog/2014/05/restful_api.html