探索DAYU-数据服务基础篇

在上期博客中，介绍了数据服务的基本组成与概念。本期博客将对数据服务API创建中所涉及的基础属性进行说明。

API基本配置

l  请求path：

    请求路径，即一个完整的url中，域名之后，查询参数之前的部分。例如图1-1中所展示的/blogs/188138

图1-1 统一资源定位符url说明

    在请求路径中，可以使用大括号{}标识路径中的参数，作为通配符，由请求时动态匹配。如上述请求路径，改写为/blogs/{blog_id}，则/blogs后携带任何参数，例如/blogs/188138和/blogs/0均会匹配至/blogs/{blog_id}，由此API统一处理。

    此外，请求路径作为url的一部分，用于识别定位唯一的API，因此相同域名下，不允许重复的请求路径出现。路径参数作为通配符，名称不具备唯一性，/blogs/{blog_id}和/blogs/{xxxx}等，均视作相同路径。

l  参数协议：

    参数协议分为ftp、http等多种协议，API中最常见使用的便是http和https协议，也就是超文本传输协议。http属于基础的网络传输协议，无状态、无连接、简单、快速、灵活、使用明文传输，在使用上较为便捷，但是安全性欠佳。https是在http协议上进行了ssl或tls加密校验的协议，能够有效验证身份以及保护数据完整性，也相对的，访问https的API，需要配置相关的SSL证书或跳过SSL校验，否则将无法访问。

l  请求方式：

    请求方式是API请求的请求类型，常见有get、post、put、delete等，一般遵循resultful风格。get常用于查询，参数一般在查询参数中；post常用于提交内容，参数一般在请求体内；put、delete则常用于更新和删除。

l  入参定义：

    入参定义主要由参数位置、参数类型、是否必填以及默认值组成。参数位置主要包括path、header、query、body四大类，path是位于请求路径中的请求参数，如果定义了path参数，则需要在请求path中也添加此参数，作为请求path的一部分；header参数是位于请求消息头中的参数，常用于传递当前信息，例如host, token等；query是位于url后的查询参数内容，以？开始，使用&连接多个参数；body是位于请求体内的参数，一般使用json格式表示。

    参数类型分为数值型与字符型两大类，数值型参数对应数据库中int、double、long等数值数据类型，字符型参数对应数据库中char、vachar、text等文本数据类型。

    是否必填以及默认值。如果设定为必填，则API在访问时，必须传入指定参数，如果非必填，则在API访问时，未传入的参数，会使用默认值进行代替。

l  安全认证：

    安全认证分为APP认证、IAM认证、无认证三大类。APP认证需要和应用协作使用，将API授权给应用后，应用可以通过应用自身的Appkey和Appsecret作为凭证，在授权有效期内访问当前API；IAM认证，使用的是华为统一身份认证服务，仅区分租户，不对子账户进行区分，使用IAM提供的token进行访问；无认证属于无防护的模式，无需认证即可访问，安全级别低，不推荐使用。

l  API目录：

                    与常见的文件夹功能相同，指定当前API保存的位置，后续可以在指定的API目录中检索当当前API。

l  标签：

    用于标记当前API的属性，对API进行分类，创建后可以通过标签快速检索定位API。

l  审核人：

             API的管理者，API对外开放后的所有相关操作，均需要由审核人审核或执行。

图1-2 API基本配置

API取数逻辑：

l  取数方式：

取数方式分为配置模式与脚本模式。配置模式可以通过简单的配置完成基础的取数逻辑，如果需要使用高阶的查询语法，可以使用脚本模式。

l  请求参数：

请求参数分为三部分，绑定参数、绑定字段、操作符。绑定参数对外开放，是用户访问API时，直接使用的参数；绑定字段对外不可见，是API调用时，实际访问的内容；操作符则是用户访问时，对参数的的处理方式。

l  返回参数：

返回参数同样分为三部分，参数名、绑定字段、参数类型。参数名对外开放，是API返回时，最终展示给用户的参数名称；绑定字段对外不可见，是API调用时，实际返回的内容；参数类型则是API调用时，数据的呈现格式，分为数值型和字符型两类。

l  排序参数：

排序参数分为四部分，参数名、字段名称、是否可选以及排序方式。参数名对外开放，是API返回时，最终展示给用户的参数名称；字段名称对外不可见，是API调用时，实际访问的内容；是否可选决定了当前排序条件是否允许移除，勾选则表示可以不使用此参数；排序方式分为升序、降序以及自定义，表示了当前参数允许使用的排序形式。