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;
            }
        }
    }
?>