PHP:API 接口规范完整版本
整体规范建议采用RESTful 方式来实施。
协议
API与用户的通信协议,总是使用HTTPs协议,确保交互数据的传输安全。
域名
应该尽量将API部署在专用域名之下。
https://api.example.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。
https://example.org/api/
api版本控制
应该将API的版本号放入URL。
https://api.example.com/v{n}/
另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。
采用多版本并存,增量发布的方式
v{n} n代表版本号,分为整形和浮点型
整形的版本号: 大功能版本发布形式;具有当前版本状态下的所有API接口 ,例如:v1,v2
浮点型:为小版本号,只具备补充api的功能,其他api都默认调用对应大版本号的api 例如:v1.1 v2.2
API 路径规则
路径又称"终点"(endpoint),表示API的具体网址。
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
举例来说,有一个API提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
HTTP请求方式
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有下面四个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
DELETE(DELETE):从服务器删除资源。
下面是一些例子。
GET /product:列出所有商品
POST /product:新建一个商品
GET /product/ID:获取某个指定商品的信息
PUT /product/ID:更新某个指定商品的信息
DELETE /product/ID:删除某个商品
GET /product/ID/purchase :列出某个指定商品的所有投资者
get /product/ID/purchase/ID:获取某个指定商品的指定投资者信息
过滤信息
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
下面是一些常见的参数。
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?producy_type=1:指定筛选条件
API 传入参数
参入参数分为4种类型:
地址栏参数
* restful 地址栏参数 /api/v1/product/122 122为产品编号,获取产品为122的信息
* get方式的查询字串 见过滤信息小节
请求body数据
cookie
request header
cookie和header 一般都是用于OAuth认证的2种途径
返回数据
只要api接口成功接到请求,就不能返回200以外的HTTP状态。
为了保障前后端的数据交互的顺畅,建议规范数据的返回,并采用固定的数据格式封装。
接口返回模板:
{
status:0,
data:{}||[],
msg:’’
}
status: 接口的执行的状态
=0表示成功
<0 表示有异常=""
Data 接口的主数据
,可以根据实际返回数组或JSON对象
Msg
当status!=0 都应该有错误信息
非Restful Api的需求
由于实际业务开展过程中,可能会出现各种的api不是简单的restful 规范能实现的,因此,需要有一些api突破restful规范原则。特别是移动互联网的api设计,更需要有一些特定的api来优化数据请求的交互。
页面级的api
把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
举例
api/v1/get-home-data 返回首页用到的所有数据
这类API有一个非常不好的地址,只要业务需求变动,这个api就需要跟着变更。
自定义组合api
把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端,服务端根据请求内容,一次性把所有数据合并返回,相比于页面级api,具备更高的灵活性,同时又能很容易的实现页面级的api功能。
规范
地址:api/v1/batApi
传入参数:
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]返回数据
{status:0,msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}
Api共建平台
RAP是一个GUI的WEB接口管理工具。在RAP中,您可定义接口的URL、请求&响应细节格式等等。通过分析这些数据,RAP提供MOCK服务、测试服务等自动化工具。RAP同时提供大量企业级功能,帮助企业和团队高效的工作。
什么是RAP?
在前后端分离的开发模式下,我们通常需要定义一份接口文档来规范接口的具体信息。如一个请求的地址、有几个参数、参数名称及类型含义等等。RAP 首先方便团队录入、查看和管理这些接口文档,并通过分析结构化的文档数据,重复利用并生成自测数据、提供自测控制台等等... 大幅度提升开发效率。
RAP的特色
强大的GUI工具 给力的用户体验,你将会爱上使用RAP来管理您的API文档。
完善的MOCK服务 文档定义好的瞬间,所有接口已经准备就绪。有了MockJS,无论您的业务模型有多复杂,它都能很好的满足。
庞大的用户群 RAP在阿里巴巴有200多个大型项目在使用,也有许多著名的公司、开源人士在使用。RAP跟随这些业务的成行而成长,专注细节,把握质量,经得住考验。
免费 + 专业的技术支持 RAP是免费的,而且你的技术咨询都将在24小时内得到答复。大多数情况,在1小时内会得到答复。
RAP是一个可视化接口管理工具 通过分析接口结构,动态生成模拟数据,校验真实接口正确性, 围绕接口定义,通过一系列自动化工具提升我们的协作效率。我们的口号:提高效率,回家吃晚饭!
参考:https://blog.csdn.net/zhs45656/article/details/52094515
PHP:API 接口规范完整版本的更多相关文章
- CHENGDU3-Restful API 接口规范、django-rest-framework框架
Restful API 接口规范.django-rest-framework框架 问题:什么是API? 答:API是接口,提供url. 接口有两个用途: 为别人提供服务,前后端分离. 为什么使用前后端 ...
- 微软提供的API的各个版本之间的区别
First Floor Software这个diff lists非常方便的给出了微软提供的API的各个版本之间的区别,比如下表是.NET 4和.NET 4.5的API变化总结.我们可以看到.NET 4 ...
- API得到Windows版本
API得到Windows版本 /** * Windows Version * https://msdn.microsoft.com/en-us/library/windows/desktop/dn48 ...
- FlappyBird模拟(不完整版本)
FlappyBird模拟(不完整版本) 准备材料 land地 sky天 pipe管道 bird小鸟 Land.js function Land(info) { this.x = info.x; thi ...
- 修改Android Studio默认的API Level(SDK版本)
原文:修改Android Studio默认的API Level(SDK版本) Android Studio(2.1.2)新建工程的时候只会让你选择最低支持的SDK版本,默认的目标编译SDK版本会以系统 ...
- API 接口规范
整体规范建议采用RESTful 方式来实施. 1. 协议 API与用户的通信协议,总是使用HTTPs协议,确保交互数据的传输安全. 2. 域名 应该尽量将API部署在专用域名之下. https://a ...
- API接口规范
协议 API与用户的通信协议,总是使用HTTPs协议,确保交互数据的传输安全. 域名 应该尽量将API部署在专用域名之下. https://api.example.com 如果确定API很简单,不会有 ...
- Restful API接口规范
1. 域名 应该尽量将API部署在专用域名之下. https://api.example.com 如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下. https://example.org ...
- Web API接口规范与测试方法
目录 1.Web API接口 1.1接口的四大特点 1.2接口文档的编写:YApi 1.3接口测试工具:Postman 2.接口规范(restful) 2.1URL设计 2.1.1 数据的安全保障(h ...
随机推荐
- QT5 Even 事件
事件的引入: 实现功能: 1.点击button 文本框两字改变成button被按下;很简单的在button上转到槽对lineEdit->setTest()设置即可; void myWidget: ...
- “编程小白学python”阅读笔记
今天在豆瓣搜索“python”关键字,搜到一本知乎周刊,读来觉得不错 编程小白学python ,作者@萧井陌, @Badger 书中提到的很多书,第一次看惊呆了,记录下来,希望每周回看此博文,坚持学习 ...
- 2018 计蒜之道 初赛 第五场 A 贝壳找房搬家
贝壳找房换了一个全新的办公室,每位员工的物品都已经通过搬家公司打包成了箱子,搬进了新的办公室了,所有的箱子堆放在一间屋子里(这里所有的箱子都是相同的正方体),我们可以把这堆箱子看成一个 x*y*z 的 ...
- hdu 4451 Dressing 衣服裤子鞋 简单容斥
Dressing Time Limit: 2000/1000 MS (Java/Others) Memory Limit: 32768/32768 K (Java/Others) Total S ...
- 【杂题】[ARC070F] Honest Or Unkind【交互】
Description 这是一道交互题 有A+B个人,编号从0~A+B-1,其中有A个人是诚实的,B个人是居心叵测的. 你想知道每个人是诚实的还是居心叵测的. 询问可以用二元组(i,j)表示,代表问编 ...
- ZJOI2010 诸神眷顾的幻想乡
题目链接:戳我 非常不好意思,因为想要排版,所以今天先只把代码贴出来,明天补题解. #include<iostream> #include<cstdio> #include&l ...
- R_Studio(学生成绩)使用主成分分析实现属性规约
对11_1_4.csv成绩表进行主成分分析处理 setwd('D:\\data') list.files() #读取数据 dat=read.csv(file="11_1_4.csv" ...
- Python3.X Selenium 自动化测试中如何截图并保存成功
在selenium for python中主要有三个截图方法,我们挑选其中最常用的一种. 挑最常用的:get_screenshot_as_file() 相关代码如下:(下面的代码可直接复制) # co ...
- Eclipse常用快捷键与IDEA中的对比.
最近从github下载了一些项目,但是看了一下使用的编译器是IDEA的,所以就下载了一个IDEA. 这边可以提供几个网址:只要是针对各个下载idea之后的一些激活相关的帮助. http://idea. ...
- 黑马lavarel教程---6、简单验证
黑马lavarel教程---6.简单验证 一.总结 一句话总结: 1.验证的最简单实例:$request的validate方法,验证通过可以继续进行,验证失败就重定向 2.中文提示可以用中文语言包 3 ...