restful-api接口的设计规范介绍

       首先，咱们得知道什么是restful-api，它产生的背景是什么，作用是什么，这样以便于我们更好的去学习和掌握这门知识。

什么是restful-api：

        EST，即Representational State Transfer的缩写。直接翻译的意思是"表现层状态转化"。
         它是一种互联网应用程序的API设计理念 ：URL定位资源，用HTTP动词（GET,POST,DELETE,DETC等）描述操作。

产生背景及作用：

       近年来移动互联网的发展，前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…），前端与后端开发人员在进行开发时需要进行交互等测试，那问题来了，在这个交互和测试环节我们如何达成一致了，方便测试呢？所以为了方便开发人员测试，提高开发效率，因此，必须有一种统一的机制来规范，于是RESTful诞生了，而且restful-api设计规范被大多数程序员认可，它可以通过一套统一的接口为 Web，iOS和Android提供服务。

       相信大家看完上面的内容应该对restful-api有了一定的了解和认识，那么接下来具体介绍一下restful-api的设计规范。

具体设计规范：

1.应该尽量将API部署在专用域名之下

http://api.douban.com/v2/user/1000001?apikey=XXX

2.应该将API的版本号放入URL

http://api.douban.com/v2/user/1000001?apikey=XXX

3.在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

http://api.douban.com/v2/book/:id (获取图书信息)
http://api.douban.com/v2/movie/subject/:id (电影条目信息)
http://api.douban.com/v2/music/:id (获取音乐信息)
http://api.douban.com/v2/event/:id (获取同城活动)

4.对于资源的具体操作类型，请求方式，由HTTP动词表示。常用的HTTP动词有下面四个(对应增/删/改/查)。

GET（select）：从服务器取出资源（一项或多项）。
eg. 获取图书信息 GET http://api.douban.com/v2/book/:id

POST（create）：在服务器新建一个资源。
eg.用户收藏某本图书 POST http://api.douban.com/v2/book/:id/collection

PUT（update）：在服务器更新资源（客户端提供改变后的完整资源）。
eg. 用户修改对某本图书的收藏PUThttp://api.douban.com/v2/book/:id/collection

DELETE（delete）：从服务器删除资源。
eg. 用户删除某篇笔记 DELETE http://api.douban.com/v2/book/annotation/:id

5.如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果

?limit=10：指定返回记录的数量
eg. 获取图书信息 GEThttp://api.douban.com/v2/book/:id?limit=10

6.服务器向用户返回的状态码和提示信息

每个状态码代表不同意思, 就像代号一样
2系 代表正常返回
4系 代表数据异常
5系 代表服务器异常

接口安全：
1.API的身份认证应该使用OAuth 2.0框架。
2.技术团队自己约定的规则

增加两个参数 time, token
time为时间戳, 用于判断接口请求是否超时
token为时间戳加密后的字符串, 加密规则只有你们技术团队自己知道