RESTful API接口设计风格

REST API(表现层状态转化)

• 简单理解为：URL定位资源，用HTTP动词（GET,POST,DELETE,PUT）描述操作。

说明

（1）每一个URI代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

规范的问题

• 因为多人开发时，会导致处理请求方式（get、post乱用），接口不统一（接口名写法千差万别），会导致各种状况都有，后期维护是个大问题，再就是请求方式也不对。
• 所以RESTFUL API的结构设计就诞生了

1. 接口命名规范
   域名：

   //将api部署在专用域名下：
   http://api.example.com
   / /或者将api放在主域名下：
   http://www.example.com/api/
   

   版本：

   将API的版本号放在url中。
   http://www.example.com/app/1.0/
   http://www.example.com/app/1.2/
   

   路径：

   路径表示API的具体网址。每个网址代表一种资源。 
   资源作为网址，网址中不能有动词只能有名词，一般名词要与数据库的表名对应。
   一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
   http://www.example.com/app/1.0/lists
   http://www.example.com/app/1.0/names
   

2. 使用标准的HTTP方法

   使用标准的HTTP方法：对于资源的具体操作类型，由HTTP动词表示。 常用的HTTP动词有四个。

   GET     :从服务器取出资源（一项或多项）
   POST    ：在服务器新建资源。
   PUT     ：在服务器更新资源。
   DELETE  ：从服务器删除资源。
   

   过滤信息

   如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
   eg：
   ?limit=10：指定返回记录的数量
   ?page=2&per_page=100：指定第几页，以及每页的记录数。
   ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
   ...
   

示例：

• 一个URl实现增删改查所有操作，具体靠http请求头部信息判断

//CRUD(增删改查) 操作学生用户的接口 /rest/1.0/userinfo

//增加一个id为1的用户    
post           /rest/1.0/userinfo           data: {id:1,name:'张三'}
//删除id为1的用户           
delete         /rest/1.0/userinfo?id=1
//修改id为1的用户           
put            /rest/1.0/userinfo?id=1      data:{id:1,name:'李四'}
//查询所有用户           
get            /rest/1.0/userinfo
//查询id为1的用户信息 
get            /rest/1.0/userinfo?id=1