RESTful API Specifications of Connectors

Overview

ROMA Connect interacts with connectors through RESTful APIs exposed by the connectors to read and write data sources. To ensure that ROMA Connect can read and write data properly, the RESTful APIs exposed by the connectors must meet ROMA Connect specifications.

ROMA Connect provides standard specifications for implementation of the data reading and writing APIs exposed by connectors. Connectors must comply with the standard specifications defined by ROMA Connect.

Data Reading API

API Specification Definition

• URI

  POST /reader

• API request

  {
      "job_name": "job_name",
      "datasource": {
          "para1": "******",
          "para2": "******",
           ...
      },
      "params": {
          "extend": {
              "ex_para1": "******",
              "ex_para2": "******",
               ...
          },
          "pagination": {
              "page_no": 1,
              "page_size": "10"
          },
          "migration": {
              "begin": **********,
              "end": **********
          }
      }
  }

• API response

  {
      "datas": [
          {
              "para1": "******",
              "para2": "******",
               ...
          },
          {
              "para1": "******",
              "para2": "******",
               ...
          },
          ...
      ]
  }

API Parameters

• Request parameters

  Table 1 Request parameters

  Parameter	Mandatory	Type	Description
  job_name	Yes	String	Task name. The value is a string of 4 to 64 characters, including letters, digits, hyphens (-), and underscores (_).
  datasource	Yes	Object	Data source object. The JSON body consists of the parameters on which the connector depends to connect to the database and all parameters.
  params	Yes	Params	Parameter object required by the connector.

  Table 2 Parameter description of params

  Parameter	Mandatory	Type	Description
  pagination	No	Pagination	Pagination object.
  migration	No	Migration	Incremental migration object.
  extend	No	Object	Extended parameters to which a connector belongs. The value is a JSON body consisting of extended parameters.

  Table 3 Parameter description of pagination

  Parameter	Mandatory	Type	Description
  page_no	No	Integer	Current page number.
  page_size	No	Integer	Number of records on each page.

  Table 4 Parameter description of migration

  Parameter	Mandatory	Type	Description
  begin	No	Date	Start time of data migration.
  end	No	Date	End time of data migration.

• Response parameters

  Table 5 Response parameters

  Parameter	Type	Description
  datas	List<Object>	List of data to be read. The value of this parameter must be in JSON array format and is determined by the connector based on the site requirements.

Data Writing API

API Specification Definition

• URI

  POST /writer

• API request

  {
      "job_name": "job_name",
      "datasource": {
          "para1": "******",
          "para2": "******",
           ...
      },
      "params": {
          "extend": {
              "ex_para1": "******",
              "ex_para2": "******",
               ...
          }
      },
      "meta-data": [
          {
              "name": "id",
              "type": "String",
              "format": "",
              "path": "datas[i].id"
          },
          {
              "name": "company",
              "type": "String",
              "format": "",
              "path": "datas[i].company"
          },
          ...
      ],
      "datas": [
          {
              "data1": "******",
              "data2": "******",
               ...
          },
          {
              "data1": "******",
              "data2": "******",
               ...
          },
          ...
      ]
  }

• API response

  {
      "num_success": "2",
      "num_fail": "0",
      "fail_datas": [
          {}
      ]
  }

API Parameters

• Request parameters

  Table 6 Request parameters

  Parameter	Mandatory	Type	Description
  job_name	Yes	String	Task name. The value is a string of 4 to 64 characters, including letters, digits, hyphens (-), and underscores (_).
  datasource	Yes	Object	Data source object. The JSON body consists of the parameters on which the connector depends to connect to the database and all parameters.
  params	Yes	Params	Parameter object required by the connector.
  meta-data	Yes	List<Meta-data>	Metadata parameter list.
  datas	Yes	List<Object>	List of data processed by the connector.

  Table 7 Parameter description of params

  Parameter	Mandatory	Type	Description
  extend	No	Object	Extended parameters to which a connector belongs. The value is a JSON body consisting of extended parameters.

  Table 8 Parameter description of meta-data

  Parameter	Mandatory	Type	Description
  name	Yes	String	Data field name.
  type	Yes	String	Data field type. The value can be String, Integer, Date, or Long.
  format	No	String	Format string of data. Format of a character string. This field needs to be specified when type is set to Date.
  path	Yes	String	Path of a field in the source data.

• Response parameter description

  Table 9 Response parameter description

  Parameter	Type	Description
  num_success	Integer	Number of times data is successfully written.
  num_fail	Integer	Number of times data failed to be written.
  fail_datas	List<Object>	List of data that fails to be processed.