[TOC] API（Application Programming Interface，應用程序編程接口）,在php中簡單的理解為兩個系統之間數據的交互。 ## oAuth OAUTH協議為用戶資源的授權提供了一個安全的、開放而又簡易的標準。與以往的授權方式不同之處是OAUTH的授權不會使第三方觸及到用戶的帳號信息（如用戶名與密碼），即第三方無需使用用戶的用戶名與密碼就可以申請獲得該用戶資源的授權，因此OAUTH是安全的。oAuth是Open Authorization的簡寫。(例子：qq登錄) 相關資料：[理解OAuth 2.0](http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html) ## RESTful 一種軟件架構風格，設計風格而不是標準，只是提供了一組設計原則和約束條件。它主要用于客戶端和服務器交互類的軟件。基于這個風格設計的軟件可以更簡潔，更有層次，更易于實現緩存等機制。[理解RESTful架構](http://www.ruanyifeng.com/blog/2011/09/restful.html) [RESTful API 設計指南](http://www.ruanyifeng.com/blog/2014/05/restful_api) 協議### API與用戶的通信協議，總是使用HTTP或者HTTPs協議。 ### 域名 應該盡量將API部署在專用域名之下。 ~~~ https://api.example.com ~~~ 如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。 ~~~ https://example.org/api/ ~~~ ### 版本 應該將API的版本號放入URL。 ~~~ https://api.example.com/v1/ ~~~ 另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github采用這種做法。 ### 路徑 路徑又稱"終點"（endpoint），表示API的具體網址。 在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用復數。 舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和雇員的信息，則它的路徑應該設計成下面這樣。 ~~~ https://api.example.com/v1/zoos https://api.example.com/v1/animals https://api.example.com/v1/employees ~~~ ### HTTP動詞 對于資源的具體操作類型，由HTTP動詞表示。 常用的HTTP動詞有下面五個（括號里是對應的SQL命令）。 ~~~ GET（SELECT）：從服務器取出資源（一項或多項）。 POST（CREATE）：在服務器新建一個資源。 PUT（UPDATE）：在服務器更新資源（客戶端提供改變后的完整資源）。 PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。 DELETE（DELETE）：從服務器刪除資源。 ~~~ 還有兩個不常用的HTTP動詞。 ~~~ HEAD：獲取資源的元數據。 OPTIONS：獲取信息，關于資源的哪些屬性是客戶端可以改變的。 ~~~ ### 過濾信息 如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。 下面是一些常見的參數。 ~~~ ?limit=10：指定返回記錄的數量 ?offset=10：指定返回記錄的開始位置。 ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。 ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。 ?animal_type_id=1：指定篩選條件 ~~~ 參數的設計允許存在冗余，即允許API路徑和URL參數偶爾有重復。比如，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。 ### 狀態碼 服務器向用戶返回的狀態碼和提示信息，常見的有以下一些（方括號中是該狀態碼對應的HTTP動詞）。 ~~~ 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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。 ~~~ ### 錯誤處理 如果狀態碼是4xx，就應該向用戶返回出錯信息。一般來說，返回的信息中將error作為鍵名，出錯信息作為鍵值即可。 ~~~ { error: "Invalid API key" } ~~~ ### 返回結果 針對不同操作，服務器向用戶返回的結果應該符合以下規范。 ~~~ GET /collection：返回資源對象的列表（數組） GET /collection/resource：返回單個資源對象 POST /collection：返回新生成的資源對象 PUT /collection/resource：返回完整的資源對象 PATCH /collection/resource：返回完整的資源對象 DELETE /collection/resource：返回一個空文檔 ~~~ ## 設計要點 ### 權限 api應用分為公開和授權的，公開接口不需要驗證權限直接可以進行調用，授權接口需要驗證調用者的身份，可通過get參數傳遞或者HTTP頭信息里面增加傳遞，接口提供方接到信息之后驗證是否有權限，再返回相對應該的數據。 ~~~ <?php $ch = curl_init(); $url = 'http://apis.baidu.com/kingtto_media/106sms/106sms?mobile=13205516161&content=%E3%80%90%E5%87%AF%E4%BF%A1%E9%80%9A%E3%80%91%E6%82%A8%E7%9A%84%E9%AA%8C%E8%AF%81%E7%A0%81%EF%BC%9A888888'; $header = array( 'apikey: 您自己的apikey', ); // 添加apikey到header curl_setopt($ch, CURLOPT_HTTPHEADER , $header); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // 執行HTTP請求 curl_setopt($ch , CURLOPT_URL , $url); $res = curl_exec($ch); var_dump($res); ?> ~~~ ### 數據格式 目前常用的接口傳輸數據格式為json和xml, json的使用量相對比較多，很多種語言都支持這種數據格式。 ~~~ { "returnstatus": "Success",---------- 返回狀態值：成功返回Success 失敗返回：Faild "message": "ok",---------- 返回信息 "remainpoint": "0",---------- 運營商結算無意義，可不用解析 "taskID": "123456",---------- 返回本次任務的序列ID "successCounts": "1"---------- 返回成功短信數 } ~~~ ~~~ XML 返回示例： ------------------------------------------------------------------------------------------------------- <?xml version="1.0" encoding="utf-8" ?> <returnsms> <returnstatus>status</returnstatus>---------- 返回狀態值：成功返回Success 失敗返回：Faild <message>message</message>---------- 返回信息 <remainpoint> remainpoint</remainpoint>---------- 運營商結算無意義，可不用解析 <taskID>taskID</taskID>---------- 返回本次任務的序列ID <successCounts>successCounts</successCounts>---------- 返回成功短信數 </returnsms> ~~~