整体规范建议采用RESTful 方式来实施。

1. 域名

应该尽量将API部署在专用域名之下。例:

https://api.admin.jsx6.com/
https://api.admin.jsx6.com/api/


2. api的版本控制


应该将API的版本号放入URL。例:

https://api.admin.jsx6.com/v{n}/

[另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。

这里我们统一采用 : 放入URL

采用多版本并存,增量发布的方式

v{n} n代表版本号,分为整形和浮点型

整形的版本号: 大功能版本发布形式;具有当前版本状态下的所有API接口 ,例如:v1,v2

浮点型:为小版本号,只具备补充api的功能,其他api都默认调用对应大版本号的api 例如:v1.1 v2.2]


3. URL的命名

 接口命名方面尽量要明显,不要用不清晰的命名,可以对返回结果定义一下,比如全部采用下划线或者驼峰式的。

 这里我们统一采用: 下划线方式命名。

 例:
  https://api.admin.jsx6.com/v{n}/user_login

4.接口验签

 为保证API接口数据的安全性的,如:

 请求来源(身份)是否合法?请求参数被篡改?请求的唯一性(不可复制),防止请求被恶意攻击。

 我们采用TOKEN+参数签名的方式来进行相关验证,并且把此次请求验签参数添加进 header 头。

 参数签名规则: sign=md5(token+字典排序(request payload)+timestamp)

 请求头应添加如下信息:

 returnFormat : json
 token : 146127581837945xxx
 sign : eyJhGciOiJJ9.eyJpZCI6IjE0NjEyNzU4MTgzNzk0NTMyNyIsImV4cCI6MTUyCB3NtKrVLx2dfIIJ9TynF...
 timeStamp : 1528806668.660056

 returnFormat:请求头里指定的返回数据格式,以方便后续扩充其他的风格。



5. 返回数据

接口返回规范详情,请前往:http://conf.jsx6.com/pages/viewpage.action?pageId=1179938

只要api接口成功接到请求,就不能返回200以外的HTTP状态。

可以请根据接口的请求接口,返回对应的HTTP状态码

并采用固定的数据格式封装。

接口返回模板:

#success

{
    "status": "200", 
    "data": {...}
}

#fail-string

{
    "status": "404", 
    "message": "No such interface", 
    "data": { }
}


#fail-object

{
    "status": "422", 
    "message": "Semantic error", 
    "data": {
        "username": "Error message", 
        "age": "Error message"
    }
}


status: 接口的执行的状态(类型全部定义为字符串),

=200 表示成功

!=200 表示有异常,只要不等于200,都应该有错误信息

message: 请求描述信息

meta: 原始数据,可以放一些服务器信息。例如:执行时间和服务器当前时间
                               

可以根据实际返回数组或JSON对象


6. 自定义组合api

注意:

把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据

这类API有一个非常不好的地址,只要业务需求变动,这个api就需要跟着变更。

建议:

对同一时间的多个请求进行合并,然后统一请求,统一返回。

所优化的只是多次请求所造成的资源开销。这种模式只适用于对一组业务联系紧密的请求进行合并请求。

把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端,服务端根据请求内容,一次性把所有数据合并返回,相比于页面级api,具备更高的灵活性,同时又能很容易的实现页面级的api功能。

组合请求只是将多个单次请求进行了封装,将多个单次请求数据放到一个请求数据里然后发给服务器进行统一内部处理。

例:

地址:api/v1/tal_api

传入参数:

    "data": [
        {
            "url": "api1", 
            "data": { }
        },
        {
            "url": "api2", 
            "data": { }
        },
        {
            "url": "api3", 
            "data": { }
        },
        {
            "url": "api4", 
            "data": { }
        }
    ]

返回数据

{
    "status": "200", 
    "data": [
        {
            "url": "api1", 
            "status": "200", 
            "data": [ ]
        },
        {
            "url": "api2", 
            "status": "200", 
            "data": { }
        },
        {
            "url": "api3", 
            "status": "404", 
            "message": "No such interface", 
            "data": { }
        },
        {
            "url": "api4", 
            "status": "404", 
            "message": "No such interface", 
            "data" : {}
        }
    ]
}



eoLinker接口管理平台 : http://api.admin.jsx6.com
功能介绍:
【接口操作历史可溯源】

 类似gitHub,接口文档的每一次改动历史应清晰记录下来。在后期接口管理和维护上,只要通过对操作历史的查看。
 目前可以记录了接口文档近十 次的操作历史,也支持接口历史一键回溯功能,算是一定程度上降低了成员对接口文档误操作的风险。


【成员权限有所限制】

 在项目开发中,由于每个团队成员在项目中担任的角色不同,所以成员对接口文档应有不同的操作权限,以确保相关接口文档的完整性和安全性。
 权限管理,通过分配适当权限给相应成员,保证开发时文档不被无关人员篡改。

【接口测试同步完成】

 编写完接口文档后,为验证接口返回值是否符合接口文档所描述的预期结果,需要对接口进行测试。
 接口本地一键化测试功能,只要将信息录入接口管理平台,就不必将接口信息重新复制到测试工具的操作。
 另外,也提供mock测试功能,通过设置假数据以验证接口的可行性。

【接口信息的导入与导出】

 项目导出


项目导入

---------------------------------------------------------------------------------------------
不忘初心 方得始终!

唯有志存高远,方能风行天下。

道之所存,虽千万人吾往矣! 情之所钟,虽千万里吾念矣~

原创作品,允许转载,转载时请务必以超链接形式标明文章 原始出处 、作者信息和本声明。否则将追究法律责任。