EchoTable REST API example

This example runs a REST API call that converts a Table parameter to a Table dataset.

Create the workflow

Create a workflow named EchoTable in the REST_API workspace.

  1. Add a Convert Data action to the workflow.

  2. Set the action’s InTable and OutTable properties, and add two sample rows to the workflow’s InTable parameter. The workflow should look like this.

EchoTable sample workflow.

  1. Save the workflow.

Register the workflow as a REST API

Register the EchoTable workflow as a REST API by carrying out the following steps:

  1. Select the EchoTable workflow in the LiveCompare hierarchy and choose ‘Register as REST API’ from the context menu to start the Register Workflow as REST API Wizard.

  2. Complete the Wizard screens as follows:

Screen What to do
Choose Input Parameter Select InTable and click Next.
Choose Output Parameter Confirm that OutTable is selected and click Next.
Properties Enter ‘EchoTable REST API’ in the Description field and click Next.
Finish - Confirm Register REST API Check your settings and click Finish.

REST API endpoints

Workflows registered as REST APIs provide the following REST API endpoints:

version.lcrs (get)

The version.lcrs endpoint returns the LiveCompare internal version and build number. This endpoint may be used to verify that the endpoints created when a workflow is registered as a REST API are available to a calling program.

run.lcrs (post)

The run.lcrs endpoint runs the workflow referenced in the REST API call. The workflow is run asynchronously.

status.lcrs (post)

The status.lcrs endpoint returns the execution status of the workflow referenced in the REST API. This endpoint should be run periodically to check for a terminal execution status (for example, Success or Error Termination).

result.lcrs (post)

The result.lcrs endpoint returns the result of the workflow referenced in the REST API. This endpoint should be run when the status.lcrs endpoint returns Success.

REST API endpoint URLs

The endpoints created by the Register Workflow as REST API Wizard have the following URLs. These URLs should be used when calling the endpoints from Postman, or from another calling program.

REST API endpoint URL
version.lcrs (get) http://<LiveCompare server>/livecompare/studio/api/version.lcrs
run.lcrs (post) http://<LiveCompare server>/livecompare/studio/api/run.lcrs
status.lcrs (post) http://<LiveCompare server>t/livecompare/studio/api/status.lcrs
result.lcrs (post) http://<LiveCompare server>/livecompare/studio/api/result.lcrs

The version.lcrs endpoint may be tested from the command line using curl, for example:

curl http://localhost/livecompare/studio/api/version.lcrs

Create an API token

The next step is to create an API token for the REST API so that in can be authenticated in the REST API call.

  1. Log in to LiveCompare as a user with Administrator privileges and click Studio tool button. to go to the LiveCompare studio.

  2. Expand the Data folder in the LiveCompare hierarchy, and select REST APIs.

  3. In the REST_APIs screen, locate the EchoTable entry and click its ‘Make API token’ button.

  4. Select an expiration period and click ‘Create API token’.

  5. In the API Tokens table, locate the REST_API/EchoTable entry and copy its Token value.

  6. Paste the value into a text file (you’ll need it later).

Run the EchoTable workflow using a REST API call

To run the EchoTable workflow using a REST API call, use the following in the Body script for the run.lcrs endpoint.

{
	"name": "REST_API/EchoTable",
	"params":
	{
		"InTable":
		{
			"inout": "in",
			"type": "table",
			"value":
			{
				"cols":
				[
					{
						"Id": "NAME",
						"Type": "string"
					},
					{
						"Id": "TYPE",
						"Type": "string"
					}
				],
				"rows":
				[
					{
						"c":
						[
							{
								"v": "VA01"
							},
							{
								"v": "TCOD"
							}
						]
					},
					{
						"c":
						[
							{
								"v": "VA02"
							},
							{
								"v": "TCOD"
							}
						]
					}
				]
			}
		},
		"OutTable":
		{
			"inout": "out",
			"type": "table",
			"value":
			{
				"cols":	[],
				"rows":	[]
			}
		}
	}
}

In the body script:

  • The “name” setting stores the name of the workflow registered as a REST API, in the format “<Workspace>/<Workflow>”.

  • The “params” setting stores the workflow’s input and output parameters, specified in the Register Workflow as REST API Wizard’s Choose Input Parameters and Choose Output Parameter screen.

    • The “InTable” structure defines the table passed to the EchoTable workflow.

      • Its “cols” structure defines the table’s columns, which should match the schema of the EchoTable workflow’s InTable parameter.

      • Its “rows” structure defines the table’s row values.

    • The “OutTable” structure defines the table returned by the EchoTable workflow/

      • It has an empty “cols” structure as placeholder for the table columns returned by the EchoTable workflow.

      • It has an empty “cols” structure as placeholder for the table columns returned by the EchoTable workflow.

In Postman, select the Authorization tab and choose ‘Bearer Token’ from the Type drop-down list. Paste the API token saved here into the Token field.

Click ‘Send’ in Postman to run the run.lcrs endpoint using the body script. The name of the REST API and its remote ID are returned in the results window.

{
	"name": "REST_API/EchoTable",
	"remoteId": "PrId_375"
}

Test script

In Postman’s Test tab, the following test script may be run when a response from run.lcrs is received.

pm.test("Successful POST request", function () {
	pm.expect(pm.response.code).to.be.oneOf([200, 201]);
	var json_data = pm.response.json();
	pm.collectionVariables.set("remoteId", json_data.remoteId);
});

This script checks that the response from run.lcrs is either 200 (success) or 201 (success, and a resource was created as a result). It also saves the remote ID from the run to a variable named remoteID. This variable is used by the status.lcrs endpoint to retrieve the execution status of the workflow, and by the result.lrcs endpoint to retrieve the workflow’s results.

Check the status of the EchoTable REST API call

To check the status of the EchoTable REST API call, use the following in the Body script for the status.lcrs endpoint.

{
	"name": "REST_API/EchoTable",
	"remoteId": "{{remoteId}}"
}

In the body script:

  • The “name” setting stores the name of the workflow registered as a REST API, in the format “<Workspace>/<Workflow>”.

  • The “remoteId” setting stores the value of the remoteId variable that was saved by the run.lcrs script.

In Postman, select the Authorization tab and choose ‘Bearer Token’ from the Type drop-down list. Paste the API token saved here into the Token field.

Click ‘Send’ in Postman to run the status.lcrs endpoint using the body script. The name of the REST API, its remote ID and its execution status are returned in the results window.

{
	"name": "REST_API/EchoTable",
	"remoteId": "PrId_375",
	"status": "Success"
}

Note that for workflows that take some time to run, the status.lcrs endpoint should be run periodically until a terminal status value is returned (either Success or Error Termination).

Retrieve the results of the EchoTable REST API call

To retrieve the results of the EchoTable REST API call, use the following in the Body script for the results.lcrs endpoint.

{
	"name": "REST_API/EchoTable",
	"remoteId": "{{remoteId}}"
}

In the body script:

  • The “name” setting stores the name of the workflow registered as a REST API, in the format “<Workspace>/<Workflow>”.

  • The “remoteId” setting stores the value of the remoteId variable that was saved by the run.lcrs script.

In Postman, select the Authorization tab and choose ‘Bearer Token’ from the Type drop-down list. Paste the API token saved here into the Token field.

Click ‘Send’ in Postman to run the result.lcrs endpoint using the body script. The following is returned in the results window.

{
	"name": "REST_API/EchoTable",
	"remoteId": "PrId_375",
	"params": {
		"OutTable": {
			"inout": "out",
			"type": "table",
			"value": {
				"cols": [
					{
						"id": "NAME",
						"type": "string"
					},
					{
						"id": "TYPE",
						"type": "string"
					}
				],
				"rows": [
					{
						"c": [
							{
								"v": "VA01"
							},
							{
								"v": "TCOD"
							}
						]
					},
					{
						"c": [
							{
								"v": "VA02"
							},
							{
								"v": "TCOD"
							}
						]
					}
				]
			}
		}
	}
}

The "OutTable" structure includes each of the table rows passed to the EchoTable workflow.

REST API developer guide