学习设计接口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 添加一个article
  • PUT /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
  • 请求方式,请求该接口的方式
  • 参数,详情列出接口需要的参数,分可选、必选
  • 返回字段说明,以文字描述出返回值比较重要的字段
  • 返回值例子,分多种状态列出该接口可能出现的返回值

文档demo

版本控制

如果在客户端应用接口还要涉及到版本控制,比如你发的 App1.0 使用的接口跟2.0 使用的可能不一样,可能会有接口字段调整,类型调整等,这时你又不能丢弃老的用户,还要兼容新的版本,那么这样的版本总体来说可以分大版本和小版本

大版本

以版本号为路径,比如 /api/v1/* ,在 App 做一次大的升级,会出现多个接口大的迁移,这时要考虑到数据库的兼容,在适当时候整体新版本里应用 v2 资源,当然这个应该是在 App 加载的时候获取的配置文件里带的,升级大版本后相关调整的接口一定要跟客户端开发者约定好,避免兼容问题

小版本

实际工作中难免会经常 fix 一些问题,或者小的需求改动,比如在登录里加个验证码,这小的改动遵循 只添加不删除 的规则,因客户端在请求接口时都会带有 App 当前的版本号,后端可根据该版本来做一些兼容,比如 1.0.1 的时候登录不用验证码, 1.0.2 的时候必须有验证码这样的需求,当然还有一些设备的兼容,比如 ios和 android 等,当一个接口里小的版本过多时就得考虑升级了

最后说:版本的升级是件"大事",一定要跟所有的相关人员密切的沟通,当然希望你的沟通者是女的吧~

 

转自:链接


本文转自SharkBin博客园博客,原文链接:http://www.cnblogs.com/SharkBin/p/5081733.html,如需转载请自行联系原作者

相关文章
|
7天前
|
数据采集 数据挖掘 API
主流电商平台数据采集API接口|【Python爬虫+数据分析】采集电商平台数据信息采集
随着电商平台的兴起,越来越多的人开始在网上购物。而对于电商平台来说,商品信息、价格、评论等数据是非常重要的。因此,抓取电商平台的商品信息、价格、评论等数据成为了一项非常有价值的工作。本文将介绍如何使用Python编写爬虫程序,抓取电商平台的商品信息、价格、评论等数据。 当然,如果是电商企业,跨境电商企业,ERP系统搭建,我们经常需要采集的平台多,数据量大,要求数据稳定供应,有并发需求,那就需要通过接入电商API数据采集接口,封装好的数据采集接口更方便稳定高效数据采集。
|
1天前
|
监控 供应链 API
为多渠道销售集成商品API接口的正式步骤指南
摘要: 在当今的零售环境中,企业通过多渠道销售策略来扩大市场覆盖范围并提高客户接触率。商品API接口的集成是实现这一目标的关键技术手段之一。本文旨在提供一套系统的步骤指南,帮助企业高效地为其多渠道销售体系集成商品API接口。
|
1天前
|
XML 自然语言处理 前端开发
NLP自学习平台提供了API接口调用服务,这些接口可以通过HTTP GET请求进行调用
【2月更文挑战第7天】NLP自学习平台提供了API接口调用服务,这些接口可以通过HTTP GET请求进行调用
8 2
|
2天前
|
缓存 监控 测试技术
ERP系统对接方案与API接口封装系列(高并发)
企业资源规划(ERP)系统是现代企业管理的核心,它集成了企业内部的各个部门和业务流程。为了实现ERP系统与其他外部系统或应用程序之间的数据交换和协作,需要对接方案。API(应用程序编程接口)是实现系统对接的常用方法之一。
|
3天前
|
文字识别 安全 API
阿里云文字识别OCR的发票凭证识别功能可以通过API接口的形式进行调用
【2月更文挑战第5天】阿里云文字识别OCR的发票凭证识别功能可以通过API接口的形式进行调用
16 5
|
3天前
|
JSON 文字识别 API
文字识别OCR服务通常提供了一种API接口
【2月更文挑战第5天】文字识别OCR服务通常提供了一种API接口
15 4
|
8天前
|
数据采集 数据挖掘 API
如何有效利用API接口进行数据采集
在当今数字化的世界中,API(应用程序编程接口)作为数据交换的桥梁,对于电商企业来说尤为重要。它们允许企业从丰富的数据源中提取必要的信息,为商业决策提供数据支持。本文将围绕如何高效地利用API进行数据采集展开讨论,并提供一些实用的代码示例。
|
20天前
|
Web App开发 前端开发 JavaScript
如何快速与呼叫中心系统CTI/API/SDK接口集成
由于呼叫中心系统涉及通信、CTI、终端设备、中继线路等技术与概念,从事信息管理系统、ERP、CRM、工单系统等的研发人员一般不是非常熟悉这部分技术,当需要提供具备呼叫中心能力的解决方案时,往往要用较多的时间来研究这些相对复杂的技术,对接过程比较长,开发调试有一定的阻力,基于此,我们提出一种更加简便高效的集成方法,可以零代码集成呼叫中心平台,实现项目快速上线。
如何快速与呼叫中心系统CTI/API/SDK接口集成
|
21天前
|
安全 前端开发 程序员
Springboot-EolinkApikit一键生成注释与一键上传API接口(idea社区版2023.1.4+apache-maven-3.9.3-bin)
Springboot-EolinkApikit一键生成注释与一键上传API接口(idea社区版2023.1.4+apache-maven-3.9.3-bin)
12 0
|
21天前
|
Java API Maven
Springboot快速搭建跨域API接口(idea社区版2023.1.4+apache-maven-3.9.3-bin)
Springboot快速搭建跨域API接口(idea社区版2023.1.4+apache-maven-3.9.3-bin)
23 0

相关产品

  • 云迁移中心