当前位置: 首页 > >

Restful API 设计规范

发布时间:

什么是Restful API


目前比较成熟的一套互联网应用程序API设计理论



应该尽量将api部署在专用域名下

https://api.baidu.com/v1/users/100001?apikey=XXX&token=XXX
就是说有一个专用的二级域名
或者是像下面这样
https://www.baidu.com/api/100001?v1/apikey=XXX&token=XXX

应该将api版本号放入url中

https://www.baidu.com/api/v1/100001?apikey=XXX&token=XXX

在Restful API设计风格中,每一个url都代表一种资源,所以url中不能有动词,只能有名词,而且所用的名词往往与数据库的表名相对应;一般来说数据库中的表都是同记录的“集合”,所以API中的名词应该使用复数,但是在中国,无所谓,比如说user表,你可以叫user,也可以叫users;



https://api.baidu.com/v1/users/:id (获取用户信息)



对于资源具体操作,用HTTP动词表示,常用的HTTP动词有下面四个(对应增/删/改/查)
GET(select):从服务器取出资源(一项或多项)POST(create):在服务器创建/新建一个资源(一项或多项)PUT(update):在服务器更新资源(客户端提供改动后的完整资源,一项或多项)DELETE(delete):在服务器删除资源(一项或多项)
如果记录数量很多,服务器不可能把数据都返回给用户,API应该提供参数,过滤返回结果

例如:?limit=10;指定返回记录数量
https://api.baidu.com/v1/goods?limit=10



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

每个状态码代表不同的意思,就像代号一样




通常有以下几种定义方式,当然你想怎么定义,都可以



2系(200、201…) 代表正常返回4系(404、403…) 代表数据异常5系(500、501) 代表服务器异常
接口安全

API的身份认证应该使用OAuth2.0框架 (这个是Restful推荐的)

不想用也可以,按照自己团队的约定,设计鉴权和验证系统

通常的约定:



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




友情链接: