Configuration Example

Prerequisites

You have obtained the endpoint address of the region where IAM and ROMA Connect are deployed.
You have obtained the ROMA Connect instance ID as well as the project ID of the region where the instance is located.
You have added authentication information to the request when you call a ROMA Connect API. Either token-based authentication or AK/SK-based authentication can be selected. For details, see Authentication. AK/SK-based authentication is recommended because it is more secure than token-based authentication.

Obtaining the Integration Application ID

All resources (such as data sources and APIs) created in ROMA Connect instances must be integrated to an application. Before creating resources, obtain their integration application ID.

If there are available integration applications, call the API for querying the applications to obtain the ID.
Example request:
```
GET /v2/{project_id}/instances/{instance_id}/apps
```
Replace the information in bold with the actual values based on the API parameter description.

Example response:
```
{
   "total" : 1,
   "size" : 1,
   "apps" : [ {
     "id" : "b2e6b145********f4b8029f95a3",
     "name" : "AppName",
     "remark" : "example"
   } ],
    ...
}
```
In the response message, apps indicates the integration applications queried and id indicates the ID of an integration application. Record the value for later use.
If no integration application is available, call the API for creating an application and obtain the ID.
Example request:
```
POST /v2/{project_id}/instances/{instance_id}/apps

{
  "name" : "AppName",
  "key" : "xxxxxx",
  "secret" : "******"
}
```
Replace the information in bold with the actual values based on the API parameter description.

Example response:
```
{
   "id" : "b2e6b145********f4b8029f95a3",
   "name" : "AppName",
   "remark" : "example",
    ...
}
```
id in the response indicates the integration application ID. Record the value for later use.

Connecting to a Data Source

Call the API for creating a data source to connect to the database whose data is to be opened and obtain the returned data source ID. The MySQL database is used as an example. For details about other types of databases, see the API parameter description.

Example request:

POST /v2/{project_id}/fdi/instances/{instance_id}/datasources

{
   "datasource_name" : "fdi_ds_mysql",
   "datasource_type" : "MYSQL",
   "content" : {
     "host" : "10.10.10.10",
     "port" : "3306",
     "database_name" : "romatest",
     "user_name" : "romatest",
     "password" : "******",
     "mode" : "default"
   },
   "app_id" : "xxxxxx",
   "description" : "test"
}

Replace the information in bold with the actual values based on the API parameter description. xxxxxx indicates the integration application ID obtained in Obtaining the Integration Application ID.

Example response:

{
   "datasource_id" : "0fd3669d********ed3160ed051",
   "datasource_name" : "fdi_ds_api_v2",
   "datasource_type" : "API",
    ...
}

datasource_id in the response indicates the data source ID. Record the value for later use.

Creating a Data Backend

By creating a data backend, the database to be opened can be converted into an API backend service.

Call the API for creating a backend API to create a custom backend and obtain the returned backend API ID.

Example request:

POST /v2/{project_id}/apic/instances/{instance_id}/livedata-apis

{
   "name" : "data_api_demo",
   "path" : "/data/test",
   "method" : "GET",
   "roma_app_id" : "xxxxxx",
   "version" : "1.0",
   "content_type" : "json",
   "return_format" : false,
   "parameters" : [
      {
         "name" : "param1",
         "in" : "Parameters",
         "required" : true
      } 
   ]
}

Example response:

{
   "id" : "bd42841c********c6d8a06e37",
   "name" : "data_backend",
   "roma_app_id" : "98df09fb********2b55ca6f3d5d",
   "content_type" : "json",
    ...
}

id in the response indicates the backend API ID. Record the value for later use.

Call the API for creating a backend API script to configure the data backend.
Example request:
```
POST /v2/{project_id}/apic/instances/{instance_id}/livedata-apis/{ld_api_id}/scripts

{
   "api_type" : "data",
   "scripts" : [ 
      {
         "ds_id" : "xxxxxx",
         "type" : "SQL",
         "object_name" : "data",
         "content" : "ZnVuY3Rpb24g******cmxkISIKfQ=="
      }
   ]
}
```
Replace the information in bold with the actual values based on the API parameter description. {ld_api_id} indicates the backend API ID obtained when you create a backend API. xxxxxx indicates the data source ID obtained in Connecting to a Data Source.

Obtaining the API Group ID

An API group is a collection of service APIs of the same type. Each API must belong to an API group. Before publishing a data API, obtain its API group ID.

An API can be called by external users only after it is published to the environment. Before publishing a data API, obtain its environment ID.

If an API group is available, call the API for querying the API groups to obtain the group ID.
Example request:
```
GET /v2/{project_id}/apic/instances/{instance_id}/api-groups
```
Replace the information in bold with the actual values based on the API parameter description.

Example response:
```
{
   "total" : 2,
   "size" : 2,
   "groups" : [ {
     "name" : "api_group_001",
     "id" : "c77f5e81d********ef2b0ac7600",
     "remark" : "group1",
      ...
   },
   ...
  ] 
}
```
groups in the response indicates the API groups queried and id indicates the API group ID. Record the ID for later use.
If no API group is available, call the API for creating an API group and obtain the group ID.
Example request:
```
POST /v2/{project_id}/apic/instances/{instance_id}/api-groups

{
   "name" : "api_group_001",
   "version" : "V2",
   "roma_app_id" : "xxxxxx"
}
```
Replace the information in bold with the actual values based on the API parameter description. xxxxxx indicates the integration application ID obtained in Obtaining the Integration Application ID.

Example response:
```
{
   "name" : "api_group_001",
   "id" : "c77f5e81d********ef2b0ac7600",
   "remark" : "group1",
    ...
}
```
id in the response indicates the API group ID. Record the value for later use.

Deploying and Publishing a Data API

Call the API for deploying a backend API and publish a data API. Then obtain the returned frontend data API ID.
Example request:
```
POST /v2/{project_id}/apic/instances/{instance_id}/livedata-apis/{ld_api_id}/deploy

{
   "deploy_front_api" : true,
   "roma_app_id" : "xxxxxx"
   "auth_type" : "APP",
   "group_id" : "yyyyyy",
   "env_id" : "DEFAULT_ENVIRONMENT_RELEASE_ID",
   "method" : "GET",
   "path" : "/data/test",
   "protocol" : "HTTPS",
   "backend_timeout" : 5000,
   "cors": false
}
```
Replace the information in bold with the actual values based on the API parameter description. {ld_api_id} indicates the backend API ID obtained in Creating a Data Backend, xxxxxx indicates the integration application ID obtained in Obtaining the Integration Application ID, and yyyyyy indicates the API group ID obtained in Obtaining the API Group ID.

Example response:
```
{
   "id" : "5e19590f54444d8a9b8fe698ce26e9fe",
   "deploy_time" : "2020-09-19T06:58:13Z",
   "api_id" : "1d0432f1a********ae7bd96ca6",
   "env_id" : "DEFAULT_ENVIRONMENT_RELEASE_ID",
    ...
}
```
api_id in the response indicates the frontend data API ID. Record the value for later use.
(Optional) When you publish a data API, request parameters cannot be added for the API. Call the API for modifying an API if you want to add the request parameters.
Example request:
```
PUT /v2/{project_id}/apic/instances/{instance_id}/apis/{api_id}

{
   "name": "Data_API",
   "type": 1,
   "req_protocol": "HTTPS",
   "req_method": "GET",
   "req_uri": "/data/test",
   "auth_type": "APP",
   "backend_type": "HTTP",
   "group_id": "c77f5e81d********ef2b0ac7600",
   "req_params": [
       {
           "name": "param01",
           "type": "STRING",
           "location": "QUERY"
       }
   ],
}
```
Replace the information in bold with the actual values based on the API parameter description. {api_id} indicates the frontend data API ID obtained when you publish a data API. The values of req_protocol, req_method, req_uri, auth_type, and group_id must be consistent with those set when the data API is published. Backend request parameters can be configured in parameters, which is optional.

Binding an Independent Domain Name to the Data API

Bind an independent domain name to the API to be exposed so that users can use the domain name to access the API.

Call the API for binding a domain name for the data API and obtain the returned domain name ID.
Example request:
```
POST /v2/{project_id}/apic/instances/{instance_id}/api-groups/{group_id}/domains

{
   "url_domain" : "www.example.com"
}
```
Replace the information in bold with the actual values based on the API parameter description. {group_id} indicates the API group ID obtained in Obtaining the API Group ID.

Example response:
```
{
   "url_domain" : "www.example.com",
   "id" : "c5e0d5ba********ae22c1a17",
   "status" : 3,
   "min_ssl_version" : "TLSv1.1"
}
```
id in the response indicates the domain name ID. Record the value for later use.
(Optional) If HTTPS is used in Deploying and Publishing a Data API, call the API for adding a certificate to the domain name to add an SSL certificate for the independent domain name.
Example request:
```
POST /v2/{project_id}/apic/instances/{instance_id}/api-groups/{group_id}/domains/{domain_id}/certificate

{
   "name" : "cert_demo",
   "private_key" : "-----Start certificate----********-----End certificate-----",
   "cert_content" : "-----Start RSA private key----- ********-----End RSA private key-----"
}
```
Replace the information in bold with the actual values based on the API parameter description. {group_id} indicates the API group ID obtained in Obtaining the API Group ID, and {domain_id} indicates the domain name ID obtained when you bind an independent domain name.

Obtaining Data API Calling Information

Call the API for querying API details to view and record the API calling information, including the API request protocol, method, path, domain name, parameters, and authentication mode.

Example request:

GET /v2/{project_id}/apic/instances/{instance_id}/apis/{api_id}

Replace the information in bold with the actual values based on the API parameter description. {api_id} indicates the frontend data API ID obtained in Deploying and Publishing a Data API.

Example response:

{
   "name": "API_test",
   "type": 1,
   "version": "V1.0",
   "req_protocol": "HTTP",
   "req_method": "GET",
   "req_uri": "/api/demo",
   "auth_type": "APP",
    ...
   "domain_name": "www.example.com",
    ...
   "req_params": [],
    ...
}

In the response, req_protocol indicates the request protocol, req_method indicates the request method, req_uri the request path, domain_name the access domain name, req_params the request parameters, and auth_type the authentication mode.

Provide the API calling information for other users to retrieve open service data by calling the data API. The procedure for calling data APIs varies depending on the API authentication mode. For details, see Calling an Open API.

Parent topic: Open Service System Data

Previous topic: Overview

Next topic: Permissions Policies and Supported Actions