Ai.KG 接口设计V1.0
郝伟 2021/05/27

1 简介

1.1 基本理念

基于HugeGraph数据库（下称HG），有以下设计理念：

  1. 基于RESTful协议，即使用url访问数据，返回json格式数据。
  2. 接口分为两类：公有数据协议和稀有数据协议。
  3. 使用SSL/TSL对链接进行加密。
  4. 支持中文。
  5. 数据与访问分离，分别使用数据服务器和接口服务器两台主机实现。
  6. 使用基于IP绑定的认证机制：
    • 数据服务器只接受接口服务器访问；
    • 接口服务器根据访问者IP提供两类接口：公共接口和私有接口；
    • 配置模块暂由开发人员在内部配置，不对外开放
  7. 将HG的强schema隐藏为弱schema，即将schema的创建过程隐藏起来。
  8. 可以添加节点、边和属性，但原则上不要修改节点、边或属性的名称。
  9. 提供文件上传以实现数据批量导入。

1.2 接口目标

接口格式为 网址+参数的方式，以下为一些接口示例，具体含意见后文定义部分：
添加节点：https://api.abc.com/vetext/ip/create?name=192.168.3.117&owner=张三
添加关系：https://api.abc.com/edge/hasPort/create?head=192.168.3.117&tail=80&date=2021050312_152241&owner=张三
查询IP：https://api.abc.com/vetex/ip/query?skip=1230&limit=100&orderby=name,desc

2 接口定义

2.1 接口格式定义

网址格式为：

[prefix]/[type]/[label]/[operation]?[paramaters]

下面分别就这几部分内容进行介绍。

2.2 prefix 网址前缀

目标主机提供的HG服务网址，如 https://api.abc.com。如果长期考虑的话，可以加上版本，如：https://api.abc.com/v1。

2.3 type 操作类型

操作类型，目前定义以下三种：

2.4 label 对象名称

待操作的对象的标签，包括节点名称或连的名称，类型为字符串，相当于关系数据库中的表名。

2.5 operation 操作命令

以下为具体操作，包括：

注：在本版本中，从数据安全角度，主要以对外查询为主，添加删除等数据修改功能暂不推荐使用。

2.6 paramaters

不同的操作会有不同的数据作为参数传递，paramaters 就是用于表示参数列表，其格式为：
key_1=value_1&key_2=value_2&...&key_n=value_n
在调用时，会转换为字典传递给后台接口。

2.7 注意事项

这里有下几点需要注意：

关于数据类型，目前HG支持以下数据类型：

1 str 字符串类型，是默认值，可以省略
2 int 整型
3 date 日期类型
4 Uuid UUID类型
5 boolean 布尔型
6 byte 字节型
7 blob 字节数组型
8 double 双精度浮点型
9 float 单精度浮点型
10 Long 长整型

3 指令详解

3.1 query

query的参数列表：

如果是经常使用的函数，可以进一步封装成函数，如：
第n页：https://api.abc.com/fun/vulnerability/query?pageno=[n]&pagecount=50

返回结果: Json格式，是对象的列表。

{
    "ip":[
      {
        "name":"192.168.3.117",
        "date":"2020/05/12 20:34:14"
      },
      {
        "name":"192.168.3.117",
        "date":"2020/05/12 20:34:14"
      },
    ]
}

3.2 create

（待定）

3.3 update 更新

（待定）

3.4 delete 删除

（待定）

4 函数详解

（待定）

5 参考资料