Restful API 的設計規范

RESTful 是目前最流行的 API 設計規范，用於 Web 數據接口的設計。降低開發的復雜性，提高系統的可伸縮性。
Restful API接口規范包括以下部分：
一、協議
API與用戶的通信協議，使用HTTPs協議或者HTTP協議，統一確定用一種。
二、域名
應該盡量將API部署在專用域名之下，如https://api.XXXXXX.com；如果多個項目創建API，把項目名稱帶上 如https://greapi.XXXXXX.com。
三、版本
可以將版本號放在HTTP頭信息中，也可以放入URL中，如https://api.XXXXXX.com/v1/,或者加入參數中
四、路徑
路徑是一種地址，在互聯網上表現為網址，在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用復數，如https://api.XXXXXX.com/v1/students。
五、HTTP動詞
對於資源的具體操作類型，由HTTP動詞表示，HTTP動詞主要有以下幾種，括號中對應的是SQL命令。
1. GET（SELECT）：從服務器取出資源（一項或多項）；
2. POST（CREATE）：在服務器新建一個資源；
3. PUT（UPDATE）：在服務器更新資源（客戶端提供改變后的完整資源）；
4. PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）；
5. DELETE（DELETE）：從服務器刪除資源；
6. HEAD：獲取資源的元數據；
7. OPTIONS：獲取信息，關於資源的哪些屬性是客戶端可以改變的。
使用方式
GET http://www.XXXXXX.com/api/user # 獲取列表
POST http://www.XXXXXX.com/api/user # 創建用戶
PUT http://www.XXXXXX.com/api/user/{id} # 修改用戶信息
DELETE http://www.XXXXXX.com/api/user/{id} # 刪除用戶信息

六、過濾信息
如果記錄數量很多，服務器不可能都將它們返回給用戶，API會提供參數，過濾返回結果，用於補充規范一些通用字段，常見的參數有：
1. ?limit=20：指定返回記錄的數量為20；
2. ?offset=8：指定返回記錄的開始位置為8；
3. ?page=1&per_page=50：指定第1頁，以及每頁的記錄數為50；
4. ?sortby=name&order=asc：指定返回結果按照name屬性進行升序排序；
5. ?animal_type_id=2：指定篩選條件。
七、狀態碼
服務器會向用戶返回狀態碼和提示信息，以下是常用的一些狀態碼，可以根據實際業務添加對應的狀態碼，需和http狀態碼對應：
1. 200 OK - [GET]：服務器成功返回用戶請求的數據；
2. 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功；
3. 202 Accepted - [*]：表示一個請求已經進入后台排隊（異步任務）；
4. 204 NO CONTENT - [DELETE]：用戶刪除數據成功；
5. 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作；
6. 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）；
7. 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的；
8. 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作；
9. 406 Not Acceptable - [GET]：用戶請求的格式不可得；
10. 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的；
11. 422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤；
12. 500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。
八、錯誤處理
字段名稱：message
示例
{"code": 200,"message": "啊哈哈","succ": true,"data": [] }
服務器返回的數據格式，應該盡量使用JSON，避免使用XML。

    <?php

    /**
     * 數據操作類
     */
    class Request{
        //允許的請求方式
        private static $method_type = array('get', 'post', 'put', 'patch', 'delete');
        //測試數據
        private static $test_class = array(
            0 => array('code'=>0,"message"=>"參數錯誤","succ"=>false, "data"=>[]),
            1 => array('code'=>200,"message"=>"啊哈哈","succ"=>true, "data"=>["name" => '托福班', 'count' => 18]),
            2 => array('code'=>200,"message"=>"啊哈哈","succ"=>true, "data"=>["name" => '雅思班', 'count' => 20]),
        );

        public static function getRequest()
        {
            //請求方式
            $method = strtolower($_SERVER['REQUEST_METHOD']);
            if (in_array($method, self::$method_type)) {
                //調用請求方式對應的方法
                $data_name = $method . 'Data';
                return self::$data_name($_REQUEST);
            }
            return self::$test_class[0];
        }

        //GET 獲取信息
        private static function getData($request_data)
        {
            $class_id = (int)$request_data['class'];
            //GET /class/ID：獲取某個指定班的信息
            if ($class_id > 0) {
                return self::$test_class[$class_id];
            } else {//GET /class：列出所有班級
                return self::$test_class;
            }
        }
    }
?>