Restful API 的設計規範

RESTful 是目前最流行的 API 設計規範，用於 Web 數據接口的設計。下降開發的複雜性，提升系統的可伸縮性。
Restful API接口規範包括如下部分：
1、協議
API與用戶的通訊協議，使用HTTPs協議或者HTTP協議，統一肯定用一種。
2、域名
應該儘可能將API部署在專用域名之下，如https://api.XXXXXX.com；若是多個項目建立API，把項目名稱帶上 如https://greapi.XXXXXX.com。
3、版本
能夠將版本號放在HTTP頭信息中，也能夠放入URL中，如https://api.XXXXXX.com/v1/,或者加入參數中
4、路徑
路徑是一種地址，在互聯網上表現爲網址，在RESTful架構中，每一個網址表明一種資源（resource），因此網址中不能有動詞，只能有名詞，並且所用的名詞每每與數據庫的表格名對應。通常來講，數據庫中的表都是同種記錄的"集合"（collection），因此API中的名詞也應該使用複數，如https://api.XXXXXX.com/v1/students。
5、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} # 刪除用戶信息

6、過濾信息
若是記錄數量不少，服務器不可能都將它們返回給用戶，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：指定篩選條件。
7、狀態碼
服務器會向用戶返回狀態碼和提示信息，如下是經常使用的一些狀態碼，能夠根據實際業務添加對應的狀態碼，需和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 - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。
8、錯誤處理
字段名稱：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;
            }
        }
    }
?>