Skip to content

Latest commit

 

History

History
100 lines (72 loc) · 4.87 KB

File metadata and controls

100 lines (72 loc) · 4.87 KB

接口设计规范和指导手册

web_api design guidance

一、 接口设计规范和说明

1.1 接口设计内容

  • 概况说明:指某项目下共同的信息以及与前端约定的信息,该部分一般不变动:
    • 名词解释
    • 投递参数注意事项
    • 实时响应结果
    • 非实时响应结果
  • 分析模块: 指某个具体分析模块对应接口设计内容:
    • 基本信息:包括接口地址、功能描述、身份验证、查询方式等信息
    • 参数:指接口需要传递的参数信息
    • 响应结果:不同类型的接口页面上对应的响应结果(接口运算分实时计算和投递计算)
    • 相关collection:指接口运行过程中涉及到插入或者更新的mongo表

1.1.1 概况说明

    1. 名词解释
名词 说明
固定值 该参数传递的是固定值,且页面不需要显示该参数(即页面上不需要调整的参数)。
conf配置 说明该参数的数据是来自配置文件中。如tasktype等,此部分是与前端约定好的一些参数。
submit_location 用来指定页面的位置;值是控制器controllor中的入口方法(action,页面菜单等)名称,用于任务面板点生成的结果表可以链接到对应的入口页面中,配置文件在common\Custom\Conf中
task_type 是用于标识对应的返回结果是【实时】还是【非实时】的。 1代表实时,2代表非实时;用于配置文件中。
    1. 投递参数注意事项

    Logic中需要对提交的数据先排序arrayKeySort,后json(json一次)提交。

    提交的参数如果是数字,优先使用没有引号的数字。可以用响应函数进行转换,整数:intval(),浮点数:floatval()。

    1. 实时响应结果

    返回一条分析记录

      提交错误 : {"success": False, "info": "错误提示"}
      提交成功 : {"success": True, "contents":['ids':{id:'56976e5a0e6da9248cada5cb', name:'report_2013'}]}
    

    返回多条分析记录 (尽量避免)

    	提交错误 : {"success": False, "info": "错误提示"}
     提交成功 : {"success": True, "contents":['ids' :[{id:'56976e5a0e6da9248cada5cb', name:'report_2013'}, {id:'56976e5a0e6da9248cada53', name:'report_2014'},]]}
    
    1. 非实时响应结果:
      提交错误 : {'success': False, "info": "错误提示"}
      提交成功 : {"success": True, "info":”成功提示”}
    

1.1.2 分析模块

    1. 基本信息 接口地址: controllor/meta/[instant,submit]/name 功能描述:该运行键执行的功能 身份验证:(验证规则根据远程服务器规则进行) 查询方式:HTTP POST
    1. 参数
    参数名(小写) 中文名 示例值 类型 来源
    function 功能水平 L1 string 页面
    function_value 功能水平 0.95 float 页面
    submit_location string conf配置
    task_type 提交类型 1 int conf配置
    task_id 任务ID 2535 int 固定值
    submit_loc_id venn_cog string conf配置

    备注: 参数名是指前端传给后台的英文参数名称,一般即接口程序中使用的变量名称。 中文名与参数名一一对应,指的是页面上某个元件如下拉框的名称(页面来源)或是参数说明(concf配置和固定值来源),一般是用户在页面上看到的文字。 示例值指的是该参数的值的样式示例。 类型指该参数的数值类型如int、float、string等 参数来源有3种,“页面”是指该参数由页面上的某个元件如‘基因集下拉框’传入,“conf配置”指该参数来源于配置文件,“固定值”指该参数不显示在页面中,但是后台程序需要传入,约定好固定取值。

    1. 响应结果:(直接粘贴接口类型对应的响应结果,见概况说明处)
     提交错误 : {"success": False, "info": "错误提示"}
     提交成功 : {"success": True, "contents":['ids':{id:'56976e5a0e6da9248cada5cb', name:'report_2013'}]}
    
    1. 相关collection :(指插入或更新的表)

1.2 设计示例