API

API是指某個應用程序封裝好的一些函數，是提供給其他應用程序或開發人員使用的。通過API，可以方便的使用的本應用程序的功能，而無需了解本應用程序的內部源碼。

Web API是API中的一類，它的功能與廣義上的API是一樣的，只是它提供給外界的是一些url規則而非函數，包括下面4個部分：

url：url鏈接；
請求方式：get、post、patch、delete等；
請求參數：json或xml格式的key-value類型數據；
響應結果：json或xml格式的key-value類型數據。

RESTful接口規范

REST是REpresentational State Transfer（表述性狀態轉移）的首字母縮寫。它是分布式超媒體系統的架構風格，最初由Roy Fielding在2000年的論文中提出。

1.什麼是RESTful：

REST-ful,其中ful代表形容詞，如helpful、powerful。這類形容詞意為"full of,having the quality of"。多加在名詞之後表示“充滿…的、易於…、可…的、富有…的、具有…的”的意思，是最常用的形容詞後綴，反義詞後綴是-less。RESTful 就代表滿足REST原則的

參考自：RESTful API

2. 什麼是RESTful規范

REST指的是一組架構約束條件和原則，通常用於Web服務的開發。它沒有提出具體的實現，只是提出了一些指導規范，供我們開發時參考。我們可以按照它的規范來，也可以忽視（不建議）。

如果一個架構符合REST的約束條件和原則，我們就稱它為RESTful架構。

3.RESTful API 設計指南

安全保障
為了安全起見，應該使用https協議。

4.表識API

用api關鍵字標識api url，與普通url加以區別。如：

www.xyz.com/api/xxx/，api.xyz.com/xxx/

5.版本控制

在url中添加版本版本，或者將版本信息放在請求頭中，請求同一資源的不同版本。如：

api.xyz.com/v1/xxx，Accept: application/vnd.xyz+json;version=1.0。

6.路徑

數據即是資源，應當使用名詞（可用復數形式）。如：www.xyz.com/book/。

HTTP動詞，即請求方法（method）
對資源的操作由請求方式決定！

HTTP請求方法資源操作 冪等安全GET 從服務器取出資源（一項或多項）是是POST在服務器新建一個資源否否PUT在服務器更新資源（客戶端提供改變後的完整資源）是否PATCH與PUT類似，用於更新資源，區別在於PATCH代表部分更新否否OPTIONS  檢測服務器所支持的請求方法，響應頭中包含一個名為“Allow”的頭，值是所支持的方法，如“GET, POST”。是是ELETEDELETE（刪除）是  否

冪等性：對同一REST接口的多次訪問，得到的資源狀態是相同的。

安全性：對該REST接口訪問，不會使服務端資源的狀態發生改變。

7.過濾

通過在url上傳遞參數的形式提交過濾條件。如：

https://api.example.com/v1/zoos?limit=10：指定返回記錄的數量

https://api.example.com/v1/zoos?offset=10：指定返回記錄的開始位置

https://api.example.com/v1/zoos?page=2&per_page=100：指定第幾頁，以及每頁的記錄數

https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序

https://api.example.com/v1/zoos?animal_type_id=1：指定篩選條件

HTTP狀態碼
1xx（信息）：通信傳輸協議級信息
1XX系列響應代碼僅在與HTTP服務器溝通時使用，平常極少使用。

2xx（成功）：表示客戶端的請求已成功接受
200（OK）：表示REST API成功執行了客戶端請求的任何操作；

201（ Created）：用戶新建資源成功。

202（Accpted）：已經接受請求並加入了處理隊列，但處理尚未完成。

204（No Content）：服務器成功處理，但沒有內容可返回。常用於PUT、POST或者DELETE請求的響應。

204響應絕不能包含消息體，因此總是在頭字段之後的第一個空行終止。

3xx（重定向 ）：表示客戶端必須執行一些其他操作才能完成其請求
301（Moved Permanently）：請求的URL已永久移走，並設計了新的URL，客戶端應該使用新的URL。

REST API應在響應的Location頭中指定新的URL，並且將舊的URL請求都定向到新的URL。

302（Found）：與301類似，但資源只是臨時被移動，客戶端應繼續使用原有URL。

302 是執行URL重定向的常用方式。

304（Not Modified）：如果客戶端在發送GET請求時附上if-Modified-Since報頭，並且從報頭指定版本開始從未修改過該資源，則說明客戶端的緩存資源是最新的， 要求客戶端使用緩存以節省資源。

此狀態代碼類似於204，響應正文必須為空。

4xx（客戶端錯誤）：此類錯誤狀態代碼指向客戶端
400（Bad Request）：這是一個通用的客戶端錯誤狀態，表示客戶端請求的語法錯誤，服務器無法理解。

401（Unauthorized）：客戶端試圖對一個受保護的資源進行操作，卻沒有提供正確的認證證書（令牌、用戶名、密碼錯誤）。

響應必須包含WWW-Authenticate頭字段，其中包含適服務器將接受哪種認證。

403（Forbidden）：與401錯誤相對，表明客戶端的請求是正確的，但用戶沒有資源的必要權限。

該響應代碼常用於一個資源只允許在特定時間段內訪問，或者允許特定IP地址的用戶訪問的情況。

404（Not Found）：服務器無法根據客戶端的請求找到資源（網頁）。

405（Method Not Allowd）：客戶端嘗試使用資源不允許的HTTP方法。比如，一個資源只支持GET方法，但是客戶端使用PUT方法訪問。

405響應必須包含Allow標頭，該標頭列出資源支持的HTTP方法。

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

5xx（服務器錯誤）：服務器負責這些錯誤狀態代碼
500（Internal Server Error）：這是一個通用的服務器錯誤響應。對於大多數web框架，如果在執行請求處理代碼時遇到了異常，它們就發送此響應代碼。