RESTful API最佳實踐(筆記)

一、參考資料

RESTful API 最佳實踐

二、我的筆記

RESTful是一種API設計規範，用于Web資料接口的設計。

這篇文章的主要内容包括：

1.URL設計

1. 動詞+賓語。RESTful的核心思想是，用戶端發出的資料操作指令都是"動詞+賓語"的結構，如GET /articles。
2. 動詞的覆寫。有些用戶端隻能使用GET和POST，伺服器必須接受使用POST模拟其他方法(通過X-HTTP-Method-Override屬性)。
3. 賓語必須是名詞。
4. 使用複數URL，如GET /articles/2。
5. 避免多級URL。資源需要多級分類，如擷取某個作者的某一類文章時，寫成GET /authors/12/categories/2不利于擴充，語義也不明确。更好的做法是，除了第一級，其他都用查詢字元串表達，如GET /authors/12?categories=2。

2. 狀态碼

狀态碼必須精确。狀态碼有以下幾大類：

狀态碼	含義
1xx	相關資訊
2xx	操作成功
3xx	重定向
4xx	用戶端錯誤
5xx	伺服器錯誤

這幾大類裡面共包含100多種狀态碼。常用的有：

200	OK
201	POST成功建立了資源
202	伺服器接收了請求，但之後再處理(異步)
400	Bad Request
401	Unauthorized
404	請求的資源不存在
500	伺服器内部錯誤

3. 應答

1. 傳回JSON，而不是純文字，這樣才能傳回标準的結構化資料。
2. 發生錯誤時，不要一律傳回200狀态碼(把錯誤資訊放在資料體裡面)。
3. 在應答中提供連結(HATEOAS)。比如通路 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}",
  ...
}           

使用者隻要記住一個URL，就可以發現其他URL。