网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备......）。
因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致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的信息：http://www.ruanyifeng.com/blog/2014/05/restful_api.html

参数

文档

接口文档常用的字段：

• 名称，该接口的名称
• 备注，该接口的一些使用场景，注意问题等说明
• 路径，表明出访问该接口的地址
• 返回值格式，通常为json
• 请求方式，请求该接口的方式
• 参数，详情列出接口需要的参数，分可选、必选
• 返回字段说明，以文字描述出返回值比较重要的字段
• 返回值例子，分多种状态列出该接口可能出现的返回值

文档demo (http://www.xuexb.com/html/api.html)

版本控制

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

大版本

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

小版本

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

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