RESTful API設計原則

RESTful（Representational State Transfer）本質是一種架構，互聯網軟件架構。

通信協議

儘可能使用https協議

部署路徑

儘量部署於專用域名，如 https://pandora128.cn

或主域名下專用路徑，如 https://pandora128.cn/fastapi

版本號

將版本號放在URL中，如百度地圖API https://api.map.baidu.com/v2

或者將版本號放在請求頭中

身份認證

使用OAuth2.0框架

路徑

Endpoint代表具體網址，路徑中應該只包含名詞，且使用複數，如 https://pandora128.cn/fastapi/docs

操作

GET（SELECT）：從服務器取出資源（一項或多項）。

POST（CREATE）：在服務器新建一個資源。

PUT（UPDATE）：在服務器更新資源（客戶端提供改變後的完整資源）。

PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。

DELETE（DELETE）：從服務器刪除資源。

HEAD：獲取資源的元數據。

OPTIONS：獲取信息，關於資源的哪些屬性是客戶端可以改變的。

過濾

對大量返回結果進行過濾，常見的有：

?limit=10：指定返回記錄的數量

?offset=10：指定返回記錄的開始位置。

?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。

?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。

?animal_type_id=1：指定篩選條件

狀態碼

200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。

201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。

202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）

204 NO CONTENT - [DELETE]：用戶刪除數據成功。

400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。

401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。

403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。

404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。

406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是隻有XML格式）。

410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。

500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷髮出的請求是否成功。

錯誤處理

出錯時返回信息，具體信息可將error作爲鍵值名，如：
{
error: “Invalid API key”
}

返回結果

返回結果儘量使用JSON，不使用XML，結果數據格式可參考以下規範

GET /collection：返回資源對象的列表（數組）

GET /collection/resource：返回單個資源對象

POST /collection：返回新生成的資源對象

PUT /collection/resource：返回完整的資源對象

PATCH /collection/resource：返回完整的資源對象

DELETE /collection/resource：返回一個空文檔

Hypermedia API

RESTful API最好做到Hypermedia，即返回結果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應該做什麼，如：https://api.github.com/

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}",
  "emails_url": "https://api.github.com/user/emails",
  "emojis_url": "https://api.github.com/emojis",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}",
  "issues_url": "https://api.github.com/issues",
  "keys_url": "https://api.github.com/user/keys",
  "label_search_url": "https://api.github.com/search/labels?q={query}&repository_id={repository_id}{&page,per_page}",
  "notifications_url": "https://api.github.com/notifications",
  "organization_url": "https://api.github.com/orgs/{org}",
  "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}",
  "organization_teams_url": "https://api.github.com/orgs/{org}/teams",
  "public_gists_url": "https://api.github.com/gists/public",
  "rate_limit_url": "https://api.github.com/rate_limit",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}",
  "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",
  "starred_url": "https://api.github.com/user/starred{/owner}{/repo}",
  "starred_gists_url": "https://api.github.com/gists/starred",
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"
}

常見設計誤區

1. URI代表資源位置，因而設計時應當用名詞，而非動詞

如賬戶轉賬

正確：POST accounts?from=張三&to=李四&money=100

錯誤：~~POST accounts/張三/李四/100~~

2. URI路徑不應加版本號，因爲URI對應的資源時同一個，只是不同版本而已

√ 正確
請求頭：version=1.0/2.0/3.0
http://***/解決方案

× 錯誤
http://***/v1.0/解決方案
http://***/v2.0/解決方案
http://***/v3.0/解決方案

參考文檔： http://www.ruanyifeng.com/blog/2014/05/restful_api.html