转载

学习设计接口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 等，当一个接口里小的版本过多时就得考虑升级了

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