REST-XSD Connector Guide

Guide topics

The REST XML connector guide includes the following topics:

Create a REST-XML asset: a detailed step-by-step tutorial on how to create a REST-XML module and assets.
Connector properties: a list of all the connector properties and their explanations.
Connector runtime behavior: a short description of the connector role on runtime.

Create REST-XSD module and assets

To create a REST-XSD asset, perform the following steps.

Step 1. Before you start

Before you start creating the REST XSD module, make sure that you have at your disposal:

XSD data source files from which to generate asset metadata files.

Step 2. Create a REST-XSD module

First, create the REST-XSD module:

> ol create module rest-xsd-module --connector rest-xsd

$ ol create module rest-xsd-module --connector rest-xsd

Step 3. View the properties of the REST-XSD connector

After creating your connector module, you can learn what properties to populate for the following steps. For more information on the REST-XSD connection properties, see Properties below.

Navigate to the module folder:

> cd rest-xsd-module

$ cd rest-xsd-module

From under the module directory, display the help menu 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:

> ol add --help
Usage: ol add [OPTIONS]

  Add Asset to Module metadata

Options:
  --verbose                              Enables verbose mode
  --verbose-debug                        Enables debug mode
  --verbose-trace                        Enables trace mode
  --additional VALUE                     Additional properties
  --xsd-file-path TEXT                   Define path to the input (request) XML file
  --operation-name TEXT                  Define name for this operation
  --http-method TEXT                     Define an HTTP method to call
  --request-url TEXT                     Define a request URL to call
  --xsd-out-file-path TEXT               Define path to the output (response) XML file
  --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: XML)
  --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

Step 4. Test the connection to the remote server

Run the ol test-connection command with the --host property to verify that the data source is accessible and that the connection properties are correct.

[module-name]> ol test connection --host https://run.mocky.io/

[module-name]$ ol test connection --host https://run.mocky.io/

Step 5. Add an asset to the REST-XSD module

After you verified the connection parameters, you can create the asset. The ol add command specifies the properties required for parsing the XSD local source file and testing the resulting asset. The command also includes a property that specifies the service endpoint on the remote server. To learn more about each property, see Properties below.

The ol add command generates the asset folder inside the module directory. The folder contains the asset configuration file ([asset-name].json) and the asset testing resources.

[module-name]> ol add --xsd-file-path ../xsd_ex/simple.xsd --request-url /v3/cd884e0c-9d4c-4e29-905e-7ce3de4b8299 --http-method POST

[module-name]$ ol add --xsd-file-path ../xsd_ex/simple.xsd --request-url /v3/cd884e0c-9d4c-4e29-905e-7ce3de4b8299 --http-method POST

Step 6. Test the REST-XSD asset

Test the asset you added to verify that you can request and receive actual business data from the data source.

From your module folder root go to assets/[asset-name]/test_data/case1/:

[module-name]> cd assets/[asset-name]/test_data/case1/

[module-name]$ cd assets/[asset-name]/test_data/case1/

To specify 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. This is a random example of an in.json file:

{
  "simple" : {
    "id" : 0,
    "user" : {
      "name" : "",
      "age" : 0,
      "salary" : 0
    },
    "roles" : {
      "role" : [ "" ]
    }
  }
}

In in.json, type the values of the input properties. In the example above, for the id key type the value 1.
Now you are ready to run ol test asset:
```
> ol test asset simple
```
```
$ ol test asset simple
```

The response from the remote server is displayed:

{
  "simple" : {
    "id" : 1,
    "user" : {
      "name" : "str1234",
      "age" : 1,
      "salary" : 3.14159
    },
    "roles" : {
      "role" : [ "str1234" ]
    }
  }
}

Properties

--xsd-file-path (required)

The local path to the input data source xsd file

--xsd-file-path (required) ../xsd_ex/simple.in.xsd

--xsd-out-file-path

If the input metadata structure of the input xsd is different from its output structure, specify the local location of the output xsd.

--xsd-out-file-path ../xsd_ex/simple.out.xsd

--operation-name

The name of the asset. If --operation-name is not provided, the asset name is identical to the xsd source file name.

--operation-name simple

--request-url

The request URL path of the business operation. The complete URL to the server is constructed by the following pattern: host + request-url. --request-url is required when the module includes more than one asset, each having an endpoint of its own, e.g., https://api.host.com/pets and https://api.host.com/users.

--request-url /v3/215985c7-d586-4ad6-afb6-0853560b1226

--http-method

The HTTP method of the operation HTTP request. If --http-method is not provided, the default HTTP method is POST.

--http-method get

--host (required)

The remote data source server address

--host https://run.mocky.io/

--profile

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

--profile dev

Runtime behavior

The REST-XSD connector receives a data request from the data consumer, converts it to XML, and transfers it via an HTTP request to the data source endpoint. The Data Source sends back its data response in an XSD format. The connector parses the response and converts it to JSON before sending it to the data consumer.