Home
Guides
Sign in

REST JSON Connector Guide

Suggest Edits

The REST JSON connector enables data consumers to connect to existing REST API services by delivering their GET or POST requests and returning the data source responses to these requests.

The REST JSON connector data flow consists of the following steps:

  1. The data consumer sends an HTTP request to the OpenLegacy REST JSON microservice. The request payload includes a JSON object specifying the data requested by the data consumer. 
  2. According to a predefined contract, the microservice converts the JSON payload to another HTTP request readable by the target REST API service. This second request can be either POST or GET.
  3. The request is sent to the target REST API service.
  4. The REST API server returns the response to the requesting microservice.
  5. The microservice processes the response according to the predefined contract and delivers it to the data consumer.

The connector configuration is done in the OpenLegacy CLI and the OpenLegacy Hub. First, use the CLI to generate an asset containing a model of the API input and output parameters and then upload the asset to an OpenLegacy Hub project. Next, in the OL Hub, generate a microservice on top of the uploaded asset. Finally, deploy the microservice on the cloud or on-prem and test it to confirm that it provides a working API to the REST service.

Prerequisites

Create REST JSON module and assets

To create a REST JSON asset, you will perform the following steps in the OpenLegacy CLI:

  1. Create a REST JSON module using the REST JSON connector.
  2. Test the connection to the remote REST JSON server. 
  3. Create a REST JSON asset. 
  4. Test the created asset by sending a test query to the remote REST JSON data source.

Step 1. Create a REST JSON module

First, create the REST JSON module:

[module-name]> ol create module rest-json-module --connector rest-json

[module-name]$ ol create module rest-json-module --connector rest-json

Step 2. Test the connection to the data source remote server

Run the ol test connection command to verify that the connection properties are correct and the remote data source is accessible. 

  1. Navigate to the module folder

    [module-name]> cd rest-json-module

    [module-name]$ cd rest-json-module

  2. From under the module directory, display the help menu of the ol test connection command to review the REST JSON connector connection properties.

    > ol test connection --help

    $ ol test connection --help

The ol test connection help menu displays the connector connection properties:

  --verbose                              Enables verbose mode
  --verbose-debug                        Enables debug mode
  --verbose-trace                        Enables trace mode
  --host TEXT                            Define host name (required)
  --http-protocol-version TEXT           HTTP Protocol Version. Available values: HTTP_1_0, HTTP_1_1, HTTP_2. Default value: HTTP_1_1
  --use-alpn TEXT                        Set to 'true' when Application-Layer Protocol Negotiation should be used
  --user TEXT                            Provide username to access the server
  --password TEXT                        Provide password to access the server
  --is-trust-self-signed TEXT            Specify if the HTTP client will trust self signed certificates (default: false)
  --timeout TEXT                         Sets the time in milliseconds before the client will drop the request. Setting zero or a negative value
                                         disables the timeout (default: 30000)
  --headers VALUE                        Provide request headers
  --format TEXT                          [JSON, XML] (default: JSON)
  --decimal-separator TEXT               (default: .)
  --client-certificate TEXT
  --client-private-key TEXT
  --generate-null-elements TEXT          (default: false)
  --auth-type TEXT                       [NONE, BASIC, OAUTH2] (default: NONE)
  --header-propagation.enabled TEXT      enables http headers propagation (default: false)
  --header-propagation.headers TEXT      List of headers to propagate
  --truststore.pems TEXT                 Provide list of pems
  --escape-strategy.escape-letters TEXT  List of additional characters to escape when building xml request.
  --oauth2.token-host TEXT
  --oauth2.token-endpoint TEXT
  --oauth2.client-id TEXT
  --oauth2.client-secret TEXT
  --oauth2.body-client-credentials TEXT  (default: false)
  --oauth2.grant-type TEXT               [CLIENT_CREDENTIALS, AUTHORIZATION_CODE, RESOURCE_OWNER_PASSWORD_CREDENTIALS, IMPLICIT] (default:
                                         CLIENT_CREDENTIALS)
  --oauth2.scope TEXT
  --oauth2.additional-headers VALUE
  --oauth2.additional-body VALUE
  --profile TEXT                         Configuration profile
  -h, --help                             Show this message and exit

To learn more about the ol test connection properties see below.

  1. Run ol test connection. 
    [module-name]> ol test connection --host https://petstore.swagger.io

    [module-name]$ ol test connection --host https://petstore.swagger.io

Step 3. Add an asset to the REST JSON module

After verifying the connection parameters, you can create a REST JSON asset by executing the ol add command. To create the asset, provide to the ol add command two JSON files, one with an example of an input to the target REST service, and the other with an example of the output. The connector uses this data to compose the input and output metadata parameters of the asset. You can also specify 

  1. Review the properties of the ol add command. 
    [module-name]> ol add --help

    [module-name]$ ol add --help

The ol add help menu displays the connector property list:

  --verbose                              Enables verbose mode
  --verbose-debug                        Enables debug mode
  --verbose-trace                        Enables trace mode
  --additional VALUE                     Additional properties
  --input-source-path TEXT               Provide local source or URL to parse input json files
  --output-source-path TEXT              Provide local source or URL to parse output json files (required)
  --request-url TEXT                     Provide a request URL (required)
  --httpMethod TEXT                      Provide an HTTP method (required)
  --asset-name TEXT                      Provide an asset name (required)
  --Content-Type TEXT                    Provide a content type (default: application/json)
  --host TEXT                            Define host name (required)
  --http-protocol-version TEXT           HTTP Protocol Version. Available values: HTTP_1_0, HTTP_1_1, HTTP_2. Default value: HTTP_1_1
  --use-alpn TEXT                        Set to 'true' when Application-Layer Protocol Negotiation should be used
  --user TEXT                            Provide username to access the server
  --password TEXT                        Provide password to access the server
  --is-trust-self-signed TEXT            Specify if the HTTP client will trust self signed certificates (default: false)
  --timeout TEXT                         Sets the time in milliseconds before the client will drop the request. Setting zero or a negative value
                                         disables the timeout (default: 30000)
  --headers VALUE                        Provide request headers
  --format TEXT                          [JSON, XML] (default: JSON)
  --decimal-separator TEXT               (default: .)
  --client-certificate TEXT
  --client-private-key TEXT
  --generate-null-elements TEXT          (default: false)
  --auth-type TEXT                       [NONE, BASIC, OAUTH2] (default: NONE)
  --header-propagation.enabled TEXT      enables http headers propagation (default: false)
  --header-propagation.headers TEXT      List of headers to propagate
  --truststore.pems TEXT                 Provide list of pems
  --escape-strategy.escape-letters TEXT  List of additional characters to escape when building xml request.
  --oauth2.token-host TEXT
  --oauth2.token-endpoint TEXT
  --oauth2.client-id TEXT
  --oauth2.client-secret TEXT
  --oauth2.body-client-credentials TEXT  (default: false)
  --oauth2.grant-type TEXT               [CLIENT_CREDENTIALS, AUTHORIZATION_CODE, RESOURCE_OWNER_PASSWORD_CREDENTIALS, IMPLICIT] (default:
                                         CLIENT_CREDENTIALS)
  --oauth2.scope TEXT
  --oauth2.additional-headers VALUE
  --oauth2.additional-body VALUE
  --profile TEXT                         Configuration profile
  -h, --help                             Show this message and exit

  1. Provide to the ol add command examples for the input and output to the target REST service.

    [module-name]> ol add --input-source-path ./postPetInput.json --output-source-path ./postPetOutput.json --request-url /v2/pet --asset-name post-pet --http-method POST

    [module-name]$ ol add --input-source-path ./postPetInput.json --output-source-path ./postPetOutput.json --request-url /v2/pet --asset-name post-pet --http-method POST

  2. Provide to the ol add command the request URL. If the request http method is GET, you can add path or query parameters to the request url.

Step 4. Test the REST JSON asset

After adding the REST JSON asset, you can test the asset by executing the ol test asset command to verify that you can request and receive actual business data from the data source.

  1.  From your module folder root go to assets/post-pet/test_data/case1/:

    [module-name]> cd assets/post-pet/test_data/case1/

    [module-name]$ cd assets/post-pet/test_data/case1/

  2. To view and edit the test input data open in.json:

    case-1> notepad in.json

    case-1$ notepad in.json

in.json contains the information sent to the remote business operation. It consists of the input keys and values that the business operation requires. 

  • An example for path parameters:
{
  "carId" : 0
}
  • An example for query parameters:
{
  "status" : ""
}

  1. In in.json, type the values of the input properties. In the example above, for carId field, type "10" and for the status field type "available".

  2. Now you are ready to run ol test asset:

    > ol test asset by_id

    $ ol test asset by_id

The response from the remote REST JSON server is displayed:

{
  "select" : [ {
    "id" : 4,
    "accountNumber" : 12346,
    "balance" : "10500",
    "polled" : "true",
    "creationDate" : "2022-01-13 08:26:26.000000 +00:00"
  } ]
}

Step 5: Push the module to the OL Hub

Now that you are sure that the REST JSON assets are operating as they should, that the connecting properties are accurate, and that the REST JSON database responds with the correct data, you can push the finalized module to the hub.

❗️

Make sure you are logged in to the OL Hub before executing ol push module.

  1.  Run the ol push module command from the module folder root:

    [module-name]> ol push module

    [module-name]$ ol push module

  2.  The CLI displays the command success status:

Module demo_module pushed successfully to the HUB

Step 6: Continue in OL Hub

Your module is now on the OL Hub and can serve as a foundation for generating services for your data consumer. 

Review the new module with assets in the OL Hub.

Next generate a microservice on top of your uploaded asset in the OL Hub.

Connector Options

--additional

key-value pairs of dynamic options

--additional [missing_value]

--request-url (required)

The URL of the request service.

--request-url /v2/pet

--output-source-path (required)

Local source or URL to parse output json files

--output-source-path ./postPetOutput.json

--http-method (required)

HTTP method

--http-method POST

--asset-name (required)

Asset name

--asset-name post-pet

--host (required)

Host name

--host MyHost

--user

Username to access the server

--user OPLSECOFR

--password

Password to access the server

--password OPENLEGA

--profile

The connection profile of ol add or ol test connection (see: Connection Profiles).

Updated 4 months ago