API开发

API开发

API开发功能，依赖数据源登记、API集合、API列表和应用管理这几个Tab下的功能，以下内容讲解中，将按照对API开发的顺序对产品功能模块进行依次说明，会包含以上Tab的详细功能点阐述。

1 服务概览

在服务概览页面，可以查看今日、近7日和近30日的API的调用情况，包括累计已发布的API数量、累计调用API的数量、累计调用API的次数以及累计调用API的成功次数，通过图表可了解在对应时间范围内的API调用的Top10以及服务的调用比率等。

在下方的列表中可查看调用API的列表，在具体调用API中包含每个API的最近调用时间，如果最近调用时间比较久远，可以考虑将API进行下线操作；还可以查看未调用API列表，若API创建成功，但未进行测试调用，可以考虑将API进行删除。

2 登记数据源

在使用数据服务之前，需要先登记数据源。

在数据源登记Tab下，选择数据源类型，填写包括数据源名称、连接串、用户名和密码等基本信息。

在数据源列表中，可以通过数据源名称进行定位搜索，也可以对数据源进行编辑和删除操作。

3 创建API集合

在创建API之前需要先创建API集合，一个API只能属于一个API集合，比如查询天气的API集合，那么可以将根据地理位置查询天气的API、根据名胜古迹查询天气的API、根据美食查询天气的API等均放在”查询天气”的API集合中，便于对同一类的API进行管理。

API集合需要填写集合名称、集合Path和描述，其中集合Path是拼接API URL地址的一部分，以标识API归属于哪个集合。

在API集合列表，可以通过创建人以及API集合名称筛选定位API集合，支持查看当前API集合下包含了哪些API。

4 创建API

登记数据源和创建API集合成功后，就可以进行API的构建了。构建API一共包括三步：填写API基本信息、配置表和参数、测试API。

4.1 第一步：配置API基本信息

序号	功能	说明
1	API名称	创建的API名称
2	API集合	API所属的集合
3	API Path	API的请求路径，也是构成API url地址的一部分
4	协议	API调用的请求协议
5	请求方式	API调用的请求方式，支持get和post
6	返回类型	API调用的返回类型，支持json
7	超时时间	API超时时间
8	描述	对API的描述
9	API标签	可以针对API添加业务标签，用于快速识别API，该功能在数据服务v1.3.7版本支持
10	数据结果缓存	若对响应时效有要求，可开启API数据结果缓存，该功能在数据服务v1.4.0版本支持
11	apiToken鉴权	若打开，可通过apiToken调用API，只需要在header中添加字段apiTOken、appKey和version即可，适用于报表、数据大屏等安全性要求不高的使用场景，该功能在数据服务v1.4.1版本支持
12	入参定义	对API调用中的请求参数绑定的入参参数的定义，支持普通入参和函数入参，函数入参中支持concat、substring等函数，即通过函数对请求参数进行二次处理，函数入参功能在数据服务v1.3.8版本支持

4.2 入参参数的配置

入参参数的设置，是为了在第二步中设置请求参数时进行绑定，请求参数一定要绑定入参参数中的其中一个，建议在请求参数中用到几个入参，就创建几个入参，若有冗余的参数，有可能会导致调用API失败。

平台支持普通入参和函数入参，可以在”入参类型”后的”?”查看注释，当前支持concat、MD5、substring和date函数，以实现对请求参数的二次处理。

需要注意的是：若在向导模式下，默认值是非必填，并且没有填写默认值，则在API调用时将忽略该参数的调用，实现参数的动态传递。

序号	功能	说明
1	参数名	入参参数的名称
2	参数位置	若请求方式选择了GET，参数位置为QUERY,若请求方式选择了POST，参数位置为BODY
3	参数类型	支持参数类型为整型、浮点型、字符串和布尔型，布尔型在数据服务v1.3.8版本支持
4	是否必填	若勾选了是，在测试和调用API时必须填写调用值，若勾选了否，则须给定一个默认值，用于测试和调用时使用；在向导模式下，若未填写默认值，且在调用API时未传参，则系统将忽略该参数
5	默认值	若勾选了是否必填的”否”，此处需要给定默认值
6	示例值	用于API调用者查看的示例值
7	描述	对于该入参参数的描述
8	函数入参的表达式	若选择了函数入参，则需要书写函数入参表达式，可以通过系统提供的函数，对入参进行二次处理，比如concat(a,b)表示将入参a和b进行拼接，a和b需要是已经创建成功的入参，函数入参功能在数据服务的v1.3.8版本支持

4.3 第二步：选择表，配置API的请求和返回参数

创建API的第二步，在选择表和参数时，由于不同数据源类型的数据结构不同，该界面也会有不同的变化，下面以经常使用的MySQL为例展示：

序号	功能	说明
1	生成方式	选择API的生成方式，支持向导和SQL模式生成API
2	数据源类型	选择数据源类型，可供选择的数据源根据数据服务的版本不同而不同，比如PostgreSQL在数据服务v1.4.1版本支持，若下拉框中没有该数据源，则当前版本不支持
3	数据源名称	选择在数据源登记模块登记的数据源名称
4	数据表	选择数据源下的数据表
5	添加返回和排序参数	在选择返回和排序参数下，点击”添加”，弹窗中展示表的所有字段，选择返回参数和排序参数
6	添加请求参数	在添加请求参数下，点击”添加请求参数”，弹窗中选择字段，请求参数支持多层嵌套，使用and或者or连接，实现诸如”(a or b) and c”的逻辑

添加完参数之后，下方会显示选择的请求参数、排序参数和返回参数，可以对参数进行配置，包括填写示例值和描述等信息。

若在向导模式下，在真正调用API时，排序参数支持传入系统参数改变升降序或者改变排序的顺序，鼠标可hover至”?”处查看详细使用方法。

序号	功能	说明
7	请求参数	需要绑定前面入参设置的参数(若没有创建入参参数，可返回上一步进行创建)，选择操作符，填写请求参数的描述，便于API的调用者可以对API有更好的理解
8	返回参数	返回参数可以修改参数的名称和类型，填写示例值和描述，也是为了让API的调用者可以对API有更好的理解
9	排序参数	排序参数可以选择排序方式，也可以对排序的字段进行上移和下移，同时，在排序参数的”?”处，也可查看系统提供的灵活设置排序参数的方法，支持改变升降序和排序顺序

需要注意的是：

一、对于请求参数中操作符的使用说明如下： 1、除了in和between操作符外，都只关联一个参数的操作符，比如”=”，绑定方式如下：

测试方式如下：

2、对于in和between操作符，参数之间用逗号进行分隔，绑定方式如下：

测试方式如下：

上图中，可以实现a between 1 and 2

同理，若在操作符中选择了in，则测试页面多个参数也使用逗号进行分隔，可以实现诸如id in (1,2)的目的。

二、返回参数的二次处理

上传Jar包对返回参数的二次处理功能，在数据服务的v1.3.9版本支持。

若对返回参数有二次处理的需求，平台支持上传Jar包达到对返回参数的二次处理，可以将对返回参数的处理逻辑在Jar中完成，然后上传Jar包，填写类名，若Jar中对返回参数进行了修改，可添加真实的返回参数，给API调用者将暴露真实的返回参数信息。

4.4 第三步：保存和测试

EasyDS提供在线功能测试，便于测试API取数逻辑配置的正确性。

在测试页面，左侧是请求参数和分页信息(默认分页页号为1，分页大小为200，最多返回3000条数据,HBase类型的数据源最多返回1W条数据)，点击开始测试，右侧会有API的测试详情和返回内容等信息。

点击”查看错误状态码”可以查看返回的错误码对应的错误原因，便于用户更好的定位失败的API的错误原因。

注：

在返回内容的”hover”提示处，在调用API时，若在向导模式下，支持使用参数”use_total_num=1”返回API的总条数。

4.5 发布API

测试成功的API便可以进行发布上线，只有发布的API才可以绑定应用，API才可以被调用。

在API列表，”更多”中可以对测试成功的API进行发布，只有测试成功的API才可以进行发布。

4.6 发布的API绑定应用

将API发布之后，点击API的名称进入详情页，可以在授权信息这里添加授权。

5 授权API应用

API调用者可以创建API应用，便于API的开发者将发布好的API绑定应用。

在API应用模块，新建应用，包括应用的名称和描述。

在API应用模块，点击”查看授权”或者应用名称，可以进入应用的详情页，在关联API处，可以看到当前应用被哪些API所绑定，可以对绑定的API进行测试，也可以解除绑定。

同时，在详情页还能看到生成的应用的APPKey和APPSecert，在API的调用中，所需要的APPKey和APPSecert信息可以直接在此进行复制。

6 调用API

EasyDS支持Restful和Java SDK两种方式调用API，在”SDK下载”或者API集市页面的右上方，可以下载详细的使用说明文档，以供用户调用参考，调用说明文档中对这两种方式均进行了详细的说明。

同时，若在创建API时，开启了”apiToken鉴权”，将API发布成功后，在API详情页的基础信息中会有apiToken内容，在header中添加apiToken、version和appKey的内容，也可以调用该API，适用于报表、数据大屏等安全性要求不高的场景。

7 API集市

API集市功能，在数据服务的v1.3.7版本支持。

对于API的调用者而言，不需要关心API的取数逻辑，可以直接在API集市查看已经发布的API，通过详情页，查看当前API的请求和返回参数，若属于需要的API，可点击”申请API”进入申请审批流程。

在申请API的弹框中，若有新建应用的权限，可直接新建应用，或绑定已有的应用，填写申请理由，默认由API的创建者进行审核，提交申请后，会弹窗提示工单进入流程协作与通知中心，可快速点击链接，进入流程协作中心查看申请工单的状态。

当工单审批成功之后，则具备调用该API的权限，通过参考调用手册，正确调用已授权的API。

8 注册API

对于API的注册功能，在数据服务的v1.4.1版本支持。

若用户已有API，也可以通过注册功能，将API通过数据服务平台进行统一管理。

在API列表Tab下点击”注册API”，注册API也包含三步，需要填写基础信息，进行参数配置以及功能测试。

8.1 第一步：配置基础信息

在注册API流程中，基础信息部分，API名称、API集合、API Path、返回类型、超时时间、描述、API标签、数据结果缓存和apiToken鉴权同新建API的业务含义。

对于协议，表示数据服务模块向待注册API服务的传输请求协议，也表示API申请者进行调用时需请求的协议。

对于请求方式，表示数据服务向待注册API服务传输请求的方法，也表示API申请者进行调用时的请求方法。

8.2 第二步：参数配置

在参数配置中，首先选择API类型的数据源，即待注册API服务的后台地址，可以在”数据源登记”页面选择API类型的数据源。

然后对注册的API添加请求参数，便于API调用者在详情页查看API的详情内容。

对于响应示例，也可以自定义成功和失败示例，也是便于API调用者查看当前API的返回内容，便于更好的使用API。

8.3 第三步：测试

注册的API配置完成后，可以在线对注册的API进行测试。

测试成功的API即可进行发布，其他操作同”新建API”类型。

9 复制、导出和锁定API

1、API导出

对于已经创建的API，支持选择后进行导出下载，可下载word或者pdf版本，下载的文档中包含API的基础信息、请求参数、排序参数和返回参数等内容。

2、API复制

点击”更多”下的”复制”，可快速复制与当前API一模一样的API，默认API名称和path后面填充时间戳，允许修改。

3、API锁定

对于API的锁定功能，在数据服务的v1.4.2版本支持。

对于自己是创建人的API，支持对API增加锁定，API锁定后，即便在安全中心赋权API有编辑等权限，依旧会受到锁定的权限控制，只有API的创建人可以对API执行锁定(数据服务平台管理员，即超管不受锁定的限制)和解锁，锁定后，只有API的创建人才可以对API进行编辑、解除应用等操作。

点击”更多”里面的锁定，API增加了锁的icon，即锁定成功，锁定后的API也可解锁。

10 API 筛选

在API列表中，支持多种维度的筛选，包括API集合、类型、创建人、数据源类型等，由于版本不一，筛选条件有可能不一样，比如API类型筛选，在数据服务的v1.4.1版本支持。

11 API在线升级

对于已发布的API，支持在线升级(该功能在v1.4.3版本支持，若无该功能，则需升级至对应版本)。

针对已经发布的API，在”更多”中选择”API升级”，

新开页面会进入API升级的四个步骤，API升级只能修改影响取数逻辑的字段，比如入参、请求和数据源等内容，

在API升级的第四个步骤，可对该API绑定的资源节点执行升级操作，全部节点处于升级成功，才可完成并退出，若有节点升级失败，可选择放弃并退出。

注：若原API开启了缓存，API升级版本将会延迟生效，延迟时间将取决于缓存的更新时间，且在第三步测试阶段，测试结果也会受到缓存数据的影响。

12 API版本历史管理

在API列表中，点击”更多”可以查看版本历史，

有下面两种情况才会产生版本历史：

发布后的API重新下线编辑再发布，且编辑的字段为影响取数逻辑的内容，比如入参、请求参数、数据源等，此时会产生版本历史；
针对已发布状态的API，执行API升级操作，会产生新的版本历史。

其他情况，比如编辑的是非取数逻辑字段，名称等，不会产生版本历史；再未发布状态下对API的修改，也不会记录版本历史。

13 API回滚和版本历史对比

在API版本历史管理弹窗中，可以选中其中两个版本，进行版本对比，对于基本信息和参数信息，若两个版本有不一致的地方，页面会标红显示，

针对某个API的回滚操作，只有该API处于发布状态，才可执行回滚，且回滚版本，即进行API的升级，API相关配置默认用回滚版本填充；

API回滚成功之后，再查看版本历史时，回滚版本将作为最新版本。

注：API升级和回滚版本互斥，若在API升级过程中，未完成或退出，而是直接关闭页面等方式，再进行回滚时将无法操作；同样，若在API回滚过程中，未完成或退出，执行API升级也将无法执行操作；

API开发和管理