学习设计接口api(转)
介绍
先说说啥是 Api
吧,以下摘自百度百科:
API
(Application Programming Interface,应用程序编程接口)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。
其实对于我们接触的 web
端开发而说, Api
就是协商好的一种规范,大家都按这个规范做事,这里主要针对 前&后端交互的接口 进行说明~
返回值约定
返回值是指当前端返回后端给出的接口时返回的数据格式,常见的有这么几种:text
, json
, xml
,现在大多数会用 json
,因为她传输数据少,可扩展性强,B格高~
方式一
我们约定返回值如果包含 errcode
则视为有错误,并会出现可选的 msg
字段,无错误则使用 items
表示循环的数据,格式如:
//提交成功,没有返回数据
{}
//获取成功,返回列表数据
{
"items":[
{
"id": 1,
"name": "前端小武"
}
]
}
//获取失败,
{
"errcode": 1
}
//提交失败
{
"errcode": 1,
"msg": "用户名为空"
}
//返回一个链接
{
"url": "/login/"
}
这种格式通常 errcode
会有一个公用的错误码,比如 1001
没登录, 2001
用户被锁定等,注意的是这个值是强制类型,前端判断:
function success (res){
if(res.errcode){//有错了
if(res.errcode === 1001){
alert('请先登录');
} else {
//no
}
} else {
//成功
}
}
方式二
约定返回值必须有 errcode
,为 0
则是成功,否则失败, errcode
也会对应公用的状态码, msg
可选, data
为数据,比如:
//成功
{
"errcode": 0
}
//提交失败
{
"errcode": 1,
"msg": "参数错误"
}
//获取链接
{
"errcode": 0,
"data": "/"
}
//获取列表
{
"errcode": 0,
"data" []
}
还有就是返回状态码,通常使用 200
,然后用 errcode
表示,但也有些以 401
未登录, 403
权限验证失败等~
返回值的格式大家约定好按着写就行,没有什么好与不好~
接口的路径风格
路径是指后端提供给前端调用该接口的地址,其实就是该接口的链接,最好以一个较为明显的词为目前开头,或者说以单独的域开头,路径还要向语义化靠拢,这里只是路径,不涉及到参数,比如:
/api/user/info
http://api.xuexb.com/user/info
注:通常是 复数
时会在词后加 s
,比如照片是 photo
,但照片集,多个照片时是 photos
,当然这不是硬性规定,具体还要看你~
隐式语义化风格
/api/photos/
获取所有照片列表,类似默认的index
为主页的意思/api/photos/create
创建照片/api/photos/delete
删除照片/api/photos/update
更新照片/api/photos/{id}
获取单个照片信息
显式语义化风格
/api/photos/get-list
获取照片列表/api/photos/create
创建照片/api/photos/delete
删除照片/api/photos/set
更新/api/photos/set-xx
更新某项/api/photos/get/{id}
创建单个
restful
REST
是一种风格,也可以说是一种思想,现在已经被广泛的应用于客户端接口的开发,这是一种以提交类型来约定行为的,比如:
GET /api/article
获取所有的article列表GET /api/article/10
获取id为10的article详细信息POST /api/article
添加一个articlePUT /api/article/10
更新id为10的article数据DELETE /api/article/10
删除id为10的article数据
查看更多关于 restful 的信息:http://www.ruanyifeng.com/blog/2014/05/restful_api.html
参数
参数分必选和可选,分数据类型,字段说明,如:
参数名 | 必选 | 类型及范围 | 说明 |
---|---|---|---|
page | false | int | 当前页, 默认为1 |
page_size | false | int | 每页多少条数据, 默认为20 |
status | true | int | 专辑状态, 1未开始, 2进行中, 3已完成, 4已删除 |
文档
我也曾有过一个不堪回首的往事,曾是没有文档的时候都是以“喊话”为途径,直接就是:xx我登录传一个用户名和密码,返回1或0~然后我发现这TMD就是个坑,当时间长了,要修改逻辑时天知道这接口是啥东西,天又知道这字段是啥意思,天知道出了bug
应该如何调试~后来我就用 excel
来写,但是因为不是二进制造成是覆盖式提交,想比对文件差异都没办法,于是我后来使用 markdown
来写接口,我现在感觉我爱上她了,用 md
写文档后可以在线的浏览,甚至可以在线编辑,很方便,当然这得后端语言的支持,不过我相信作为前端的你应该完全可以用 nodejs
搞定她~
接口文档常用的字段:
- 名称,该接口的名称
- 备注,该接口的一些使用场景,注意问题等说明
- 路径,表明出访问该接口的地址
- 返回值格式,通常为
json
- 请求方式,请求该接口的方式
- 参数,详情列出接口需要的参数,分可选、必选
- 返回字段说明,以文字描述出返回值比较重要的字段
- 返回值例子,分多种状态列出该接口可能出现的返回值
版本控制
如果在客户端应用接口还要涉及到版本控制,比如你发的 App1.0
使用的接口跟2.0
使用的可能不一样,可能会有接口字段调整,类型调整等,这时你又不能丢弃老的用户,还要兼容新的版本,那么这样的版本总体来说可以分大版本和小版本
大版本
以版本号为路径,比如 /api/v1/*
,在 App
做一次大的升级,会出现多个接口大的迁移,这时要考虑到数据库的兼容,在适当时候整体新版本里应用 v2
资源,当然这个应该是在 App
加载的时候获取的配置文件里带的,升级大版本后相关调整的接口一定要跟客户端开发者约定好,避免兼容问题
小版本
实际工作中难免会经常 fix
一些问题,或者小的需求改动,比如在登录里加个验证码,这小的改动遵循 只添加不删除 的规则,因客户端在请求接口时都会带有 App
当前的版本号,后端可根据该版本来做一些兼容,比如 1.0.1
的时候登录不用验证码, 1.0.2
的时候必须有验证码这样的需求,当然还有一些设备的兼容,比如 ios
和 android
等,当一个接口里小的版本过多时就得考虑升级了
最后说:版本的升级是件"大事",一定要跟所有的相关人员密切的沟通,当然希望你的沟通者是女的吧~
转自:链接
学习设计接口api(转)的更多相关文章
- 前后端分离&接口API设计学习报告
接口API设计学习报告 15331023 陈康怡 什么是API? API即Application Programming Interface.API是一种通道,负责一个程序与另一个程序的沟通.而对于w ...
- 推荐一款接口 API 设计神器!
今天栈长给大家推荐一款接口 API 设计神器,传说中的,牛逼哄洪的 Swagger,它到底是什么?今天为大家揭开谜底! Swagger是什么? 官网:https://swagger.io/ Swagg ...
- 【转】App开放接口api安全性—Token签名sign的设计与实现
前言 在app开放接口api的设计中,避免不了的就是安全性问题,因为大多数接口涉及到用户的个人信息以及一些敏感的数据,所以对这些接口需要进行身份的认证,那么这就需要用户提供一些信息,比如用户名密码等, ...
- App开放接口api安全性的设计与实现
前言 在app开放接口api的设计中,避免不了的就是安全性问题,因为大多数接口涉及到用户的个人信息以及一些敏感的数据,所以对这些接口需要进行身份的认证, 那么这就需要用户提供一些信息,比如用户名密码等 ...
- App开放接口api安全性—Token签名sign的设计与实现
前言 在app开放接口api的设计中,避免不了的就是安全性问题,因为大多数接口涉及到用户的个人信息以及一些敏感的数据,所以对这些接口需要进行身份的认证,那么这就需要用户提供一些信息,比如用户名密码等, ...
- 组件接口(API)设计指南-文件夹
组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...
- App开放接口API安全性 — Token签名sign的设计与实现
在app开放接口API的设计中,避免不了的就是安全性问题. 一.https协议 对于一些敏感的API接口,需要使用https协议. https是在http超文本传输协议加入SSL层,它在网络间通信是加 ...
- APP开放接口API安全性——Token令牌Sign签名的设计与实现
在APP开放接口API的设计中,避免不了的就是安全性问题. 一.https协议 对于一些敏感的API接口,需要使用https协议.https是在http超文本传输协议加入SSL层,它在网络间通信是加密 ...
- App开放接口API安全性之Token签名Sign的设计与实现
前言 在app开放接口api的设计中,避免不了的就是安全性问题,因为大多数接口涉及到用户的个人信息以及一些敏感的数据,所以对这些接口需要进行身份的认证,那么这就需要用户提供一些信息,比如用户名密码等, ...
随机推荐
- poj 2403
http://poj.org/problem?id=2403 题意:就是给你m个单词,以及n段对话.每一个单词都有所对应的价值.求对话中的价值总和 题解:很简单,就是用单词和价值对应起来,然后再寻找就 ...
- Appium+Robotframework实现Android应用的自动化测试-6:一个简单的例子
万事具备,只欠编码! 下面看一个简单的示例,这个示例验证Android手机自带的通讯录的添加联系人的操作是否成功.这个例子是Appium官网自带的示例,有兴趣的同学也可以自己下载来研究和学习,下载地址 ...
- centos6.5 mysql开机启动
可参考:centos6.5 nginx开机启动 /etc/init.d/下添加mysqld文件,内容如下: #!/bin/sh # Copyright Abandoned TCX DataKonsul ...
- MySQL binlog 组提交与 XA(分布式事务、两阶段提交)【转】
概念: XA(分布式事务)规范主要定义了(全局)事务管理器(TM: Transaction Manager)和(局部)资源管理器(RM: Resource Manager)之间的接口.XA为了实现分布 ...
- Java for LeetCode 226 Invert Binary Tree
Invert a binary tree. 4 / \ 2 7 / \ / \ 1 3 6 9 to 4 / \ 7 2 / \ / \ 9 6 3 1 Trivia: This problem wa ...
- CentOS 7 关闭图形界面
CentOS 7 关闭图形界面 查看/etc/inittab如下: # systemd uses 'targets' instead of runlevels. # by default, there ...
- 关于C语言中的转义字符
1.转义字符的分类 1. 1一般转义字符 这种转义字符,虽然在形式上由两个字符组成,但只代表一个字符.常用的一般转义字符为: \a \n \t \v \b \r ...
- plsql客户端显示菜单等
不小心把plsql的左边的都关了,如图 菜单条---工具---浏览器. 即可.
- 在Eclipse中手动安装pydev插件,eclipse开发python环境配置
最近在学习Python,因为我是做java的,用惯了eclipse,所以就想用eclipse开发python,但是配置开发环境的时候发现按照网上的配置大多不行,而且都是用的在线安装,很垃圾,没办法,自 ...
- 【XLL 框架库函数】 debugPrintf
通过调用 Windows SDK 函数 OutputDebugStringA 在激活的调试器中输出字符串信息.如果应用程序没有调试器,那么系统调试器就会显示字符串.如果这两种调试器都没使用的话,deb ...