RESTful API规范 接口URL路径设计与返回结果数据格式
编写API有什么好处呢？由于API就是把Web App的功能全部封装了，所以，通过API操作数据，可以极大地把前端和后端的代码隔离，使得后端代码易于测试，前端代码编写更简单。
编写REST API，实际上就是编写处理HTTP请求的async函数，不过，REST请求和普通的HTTP请求的区别：
REST请求仍然是标准的HTTP请求，但是，除了GET请求外，POST、PUT等请求的body是JSON数据格式，请求的Content-Type为application/json；
REST响应返回的结果是JSON数据格式，因此，响应的Content-Type也是application/json。
url 即资源
rest接口是围绕“资源”展开的，利用HTTP的协议，其实rest本也可以和HTTP无关，但是现在大家普遍的使用rest都是依托于HTTP协议。HTTP 的url即资源。
RFC 3986定义了通用的URI语法：
URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]
scheme: 指底层用的协议，如http、https、ftp
host: 服务器的IP地址或者域名
port: 端口，http中默认80
path: 访问资源的路径，就是咱们各种web 框架中定义的route路由
query: 为发送给服务器的参数
fragment: 锚点，定位到页面的资源，锚点为资源id
Rest设计原则
那么怎么样可以设计成REST的架构规范呢? 需要符合如下的一些原则：
1. 每一个URI代表一种资源;
2. 同一种资源有多种表现形式(xml/json);
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。
URL设计规范
1) uri末尾不需要出现斜杠/
2) 在uri中使用斜杠/是表达层级关系的。
3) 在uri中可以使用连接符 -, 来提升可读性。
4) 在uri中不允许出现下划线字符 _.
5) 在uri中尽量使用小写字符。
6) 在uri中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。
7) 在uri中使用复数形式
符合上述REST原则的架构方式被称作为 RESTful 规范。
CURD操作
GET: 获取资源
POST: 新建资源
PUT：在服务器更新资源（向客户端提供改变后的所有资源）
PATCH: 在服务器更新资源（向客户端提供改变的属性）
DELETE：删除资源
PATCH一般不用，用PUT
http://xxx.com/api/users; // GET请求方式 获取所有用户信息 http://xxx.com/api/users; // POST请求方式 添加新的用户 http://xxx.com/api/users/1; // GET请求方式 获取标识为1的用户信息 http://xxx.com/api/users/1; // DELETE请求方式 删除标识为1的用户信息 http://xxx.com/api/users/1; // PUT/PATCH请求方式，更新标识为1的用户全部部分信息
QUERY 资源过滤
当我们只需要获取部分数据时，可通过参数限制返回的结果集
limit：指定返回记录数量
offset：记录开始位置
direction：请求数据的方向，取值prev-上一页数据；next-下一页数据
page：第几页
per_page：每页条数
total_count：总记录数
total_pages：总页数，等于page时，表示当前是最后一页
sort：column1,column2排序字段
orderby：排序规则，desc或asc
q：搜索关键字（uri encode之后的）
例如，返回第2页评论，每页10项，按时间排序：
GET /api/products/123/reviews?page=2&size=10&sort=time
返回结果
GET /collections 返回资源列表
GET /collections/:id 返回单独的资源
POST /collections 返回新生成的资源对象
PUT /collections/:id 返回完整的资源对象
PATCH /collections/:id 返回被修改的属性（也可返回完整的资源对象）
DELETE /collections/:id 返回一个空文档（也可返回完整的资源对象）
返回数据格式
服务器端返回的数据格式可以是XML、或json. 或者直接返回状态码的方式。
RESTful规范中的请求应该返回统一的数据格式。对于返回的数据，一般会包含如下字段:
1) code: http响应的状态码（查看http状态码说明）。
2) status: 包含文本, 比如：'success'(成功), 'fail'(失败), 'error'(异常)
HTTP状态响应码
在500-599之间为 'fail';
在400-499之间为 'error',
其他一般都为 'success'。
对于响应状态码为 1xx, 2xx, 3xx 这样的可以根据实际情况可要可不要。
3) message: 当status的值为 'fail' 或 'error'时，需要添加 message 字段，用于显示错误信息。
4) data: 当请求成功的时候, 返回的数据信息。
当状态值为 'fail' 或 'error' 时，data仅仅包含错误原因或异常信息等。
返回成功的响应JSON格式一般为如下:
{
"code": 200,
"status": "success",
"data": [{
"userName": "tugenhua",
"age": 31
}]
}返回失败的响应json格式为如下:
{
"code": 401,
"status": "error",
"message": '用户没有权限',
"data": null
}
共 0 条评论