2、RESTFUL设计规范

    前端设备的多样性促进API架构的流行，甚至出现“API优先”的设计思想。而RESTFUL API 是目前比较成熟的一套互联网应用程序的API设计理论，如何设计一套合理好用的API，就是本篇文章的重点，废话少说，开始正题。

1、协议

上篇已说到“RESTFUL是基于HTTP的设计风格和开发方式”

结论：API与用户的通信协议，总是使用HTTP/HTTPS

 

2、域名：对外开放访问的必须条件

优先将API放在专用域名下

https://api.example.com

API简单且不会再进一步扩展时，可考虑放主域名下

https://api.example.com/api/

 

3、版本：应该将API的版本放入URL中

相较于将版本信息放到HTTP头信息中，体现在URL中更直观

https://api.example.com/v1/

 

4、通过媒体类型指定版本信息

Accept：application/json

 

5、路径：路径又称“终点”，表示API的具体地址（限名词）

https://api.example.com/v1/zoos

https://api.example.com/v1/animals

https://api.example.com/v1/tigers

 

注意事项：

（1）URL的命名必须全部小写

（2）URL中的资源的命名必须是名词且为复数形式

（3）URL中不能出现-，必须用_替代

（4）URL必须是易读的

（5）URL一定不可暴露服务器架构（如何理解）

 

6、HTTP动词：表示资源的具体操作类型

常用动词如下（括号里对应的是SQL命令）

GET（SELECT）	从服务器中取出资源（一项或多项）
POST（CREATE）	在服务器新建一个资源
PUT（UPDATE）	在服务器更新资源（客户端提供改编后的完整资源--整行数据）
PATCH（UPDATE）	在服务器更新资源（客户端提供改变的属性-部分字段）
DELETE（DELETE）	从服务中删除资源
HEAD	获取资源的元素据
OPTIONS	获取信息，关于资源的哪些属性是客户端可以更改的

 

示例如下：

GET  /tigers	列出所有的老虎
POST /tigers	增加一只老虎
PUT /tigers/name	更新某只特定老虎的信息（提供某只老虎的所有信息）
PATCH  tigers/name	更新某只老虎的信息（提供某只老虎的部分信息）
DELETE  tigers/name	删除某只特定的老虎

 

 

7、过滤信息：如果记录数过多，服务器不可能返回所有的数据给用户，可通过参数过滤返回结果

常见参数如下

?limit=10	指定返回记录的数量
?offset=10	指定返回记录的开始位置
?page=2&per_page=10	指定页数及每页记录数
?sortby=name&order=asc	指定返回结果排序规则
?name=tidd	指定筛选条件

 

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复，

如GET /tigers/tidd 与  GET /tigers?name=tidd

 

8、状态码

 

状态码	描述
1xx	代表请求已被接受，需要继续处理
2xx	请求已成功，请求所希望的响应头或数据体将随此响应返回
3xx	重定向
4xx	客户端原因引起的错误
5xx	服务端原因引起的错误

 

更多状态码信息见“RESTFUL中HTTP状态码归纳”

 

9、认证：先获取Access_Token，再通过Token调用身份认证的API

获取token时必须在响应中包含失效时间的参数

{ "access_token"："xxxxxxx", "token_type"："login", "expires_in"：60 }

 

客户端在请求需要认证的API时，必须在请求头Authorization中带上access_token

Authorization：login xxxxx

 

超过指定时间后，access_token过期，服务端应返回相关提示

 

10、返回结果

常见返回方式

（1）将错误放到HTTP响应头

（2）将错误放到HTTP响应实体中

 

注意事项：

（1）API一定不可返回1xx类型状态码

（2）必须返回出错的响应信息

 

参考资料：

              http://www.ruanyifeng.com/blog/2014/05/restful_api.html

              https://www.cnblogs.com/softidea/p/9712565.html