[PHP] API 開發規範

1、數據傳輸方式說明
GET（SELECT）：從服務器取出資源（一項或多項）
POST（CREATE）：在服務器新建一個資源
PUT（UPDATE）：在服務器更新資源（客戶端提供完整資源數據）
PATCH（UPDATE）：在服務器更新資源（客戶端提供須要修改的資源數據）
DELETE（DELETE）：從服務器刪除資源
★沒有嚴格要求時，能夠只用 GET 與 POST 兩種方式。

2、狀態碼說明
當 GET, PUT 和 PATCH 請求成功時，要返回對應的數據，及狀態碼 200，即 SUCCESS
當 POST 建立數據成功時，要返回建立的數據信息，及狀態碼 201，即 CREATED
當 DELETE 刪除數據成功時，不返回數據，狀態碼要返回 204，即 NO CONTENT
當 GET 不到數據時，狀態碼要返回 404，即 NOT FOUND
任什麼時候候，若是請求有問題，如校驗請求數據時發現錯誤，要返回狀態碼 400，即 BAD REQUEST
當 API 請求須要用戶認證時，若是 request 中的認證信息不正確，要返回狀態碼 401，即NOT AUTHORIZED
當 API 請求須要驗證用戶權限時，若是當前用戶無相應權限，要返回狀態碼 403，即FORBIDDEN

3、Header 設置
一、緩存設置
/ 示例，看狀況，有些數據是容許被緩存一段時間的 /
if ($time) { // 單位：秒

header("Cache-Control: max-age=$time");
header("Date: " . date("r", time()));
header("Expires: " . date("r", time() + $time));
header("Pragma: cache");

} else {

header("Expires: " . date("r", time()));
header("Cache-Control: no-cache");
header("Pragma: no-cache");

}
二、跨域設置
/ 示例，看狀況，不是全部接口都有跨域問題 /
if (isset($_SERVER['HTTP_ORIGIN']) && $_SERVER['HTTP_ORIGIN']) {

header('Access-Control-Allow-Origin: ' . $_SERVER['HTTP_ORIGIN']);
header('Access-Control-Allow-Methods: POST, GET, OPTIONS');
header('Access-Control-Allow-Credentials: true');
header('Access-Control-Allow-Headers: Content-Type');
header('Access-Control-Max-Age: 86400');

}
三、數據傳輸格式設置（json，推薦使用）
header('Content-Type: application/json; charset=utf-8');

4、數據校驗
全部服務端接收到的參數，均須要在服務端進行校驗，越嚴格越好，寧願錯殺，毫不放過！！
若是客戶端發送的數據不正確或不合理，服務器端通過校驗後直接向客戶端返回400錯誤及相應的數據錯誤信息。

一、數據類型校驗，最基本的判斷，必不可少
若是字段類型是int，那麼給字段賦「字符串」的值則報錯
若是字段類型是bool，那麼給字段賦 true 或 false 以外的值都報錯
二、數據格式校驗，特定數據，特殊判斷
如郵箱或密碼，其賦值必須知足相應的正則表達式，纔是正確的輸入數據
如日期，正則匹配或日期解析，不正確時都報錯
三、數據邏輯校驗，用得最多，要求也最嚴
若是數據包含出生日期和年齡兩個字段，可是這兩個字段的數據不一致，則數據校驗失敗
若是是當前登陸人的年齡信息，可是範圍不在 18~90 之間，則檢驗失敗
若是是狀態值只有 [-1,0,1] 三個狀態，可是數據不在三值內，則檢驗失敗

5、登陸與權限驗證
經常使用的認證機制是 Basic Auth 和 OAuth，API 開發中，除非 API 很是簡單，且沒有潛在的安全性問題，不然，認證機制是必須實現的，並應用到API中去。Basic Auth 即簡單登陸；OAuth 建議使用 CAS 實現單點登陸機制。登陸完成後，可以使用 token 或 cookie 進行安全校驗。

權限機制是對 API 請求更近一步的限制，只有經過認證的用戶符合權限要求，才能訪問API。通常是業務系統內部規劃與分配權限，而後進一步的驗證，關鍵性數據必須有嚴格的權限斷定。

6、接口定義與數據規範
一、接口 URL 定義規則：所有統一用小寫字母，多單詞間以中劃線「-」鏈接，不以「/」結尾
二、數據規範：
調用接口參數示例，注意傳參字段類型，不可混淆使用。
/ 示例爲搜索用戶列表 /
{

"id": 1,
"username": "wang",
"nickname": "小王",
"realname": "雲鵬",
"role_id": 2,
"group_id": 3,
"email": "@dxy.cn",
"phone": "136",
"status": 1,
"created_start": "2017-06-22 ",
"created_end": "2017-06-28",
"per_page": 20,
"page": 1

}
正確返回示例，數據列表必須是數組型，例如示例中的「items」。
★注意：PHP 中只有 key 爲 0、一、二、… 的數組在 json_encode 時，會被轉換成 json數組。
{

"code": 200,
"success": true,
"results": {
    "pager": {
        "page": 1,            # 當前是第幾頁
        "pages": 3,           # 總共多少頁
        "per_page": 10,       # 每頁多少數據
        "has_next": true,     # 是否有下一頁數據
        "has_prev": false,    # 是否有前一頁數據
        "total": 27           # 總共多少數據
    },
    "items": [
        {
            "id": "2",
            "username": "test",
            "nickname": "sSgysf",
            "realname": "",
            "email": "vXfxM@qq.com",
            "phone": "",
            "status": "1",
            "created": "2017-06-19 18:27:58",
            "modified": "2017-07-04 19:11:03",
            "roles": [],
            "groups": []
        },
        {
            "id": "3",
            "username": "aaa",
            "nickname": "sSgysf",
            "realname": "",
            "email": "",
            "phone": "",
            "status": "1",
            "created": "2017-06-20 14:16:58",
            "modified": "2017-06-20 18:06:02",
            "roles": [],
            "groups": []
        },
    ]
}

}
// 系統內還設置一個 per_page_max 字段，用於標記系統容許的每頁最大記錄數，當 per_page 值大於 per_page_max 值時，每頁記錄條數爲 per_page_max。

錯誤信息返回示例
{

"code": 401,
"success": false,
"message": "id 參數錯誤"

}