REST Data Server

Jump to Section

The REST Data server exposes an API to interact with industrial data, providing access to applications that need to make requests for data on demand. The API exposes connection inputs and outputs and instances as well as pipelines.

Pipelines provide a way to build out your own API, where each Pipeline can perform specific operations, like getting machine state, retrieving historical data, changing set points, etc. This is a powerful approach, as the API can remain the same between multiple factories, but the pipeline plumbing can change depending on the specific solutions in each factory. For example, maybe CreateWorkOrder in one factory routes to Maximo’s REST interface and in another interacts with SQL.

Enable the REST Data Server

To enable the REST Data server do the following:

  1. Go to Settings under Manage in the main menu
  2. Enable HTTPS (recommended). By default, this will use a self-signed certificate
  3. Keep Allow Anonymous disabled unless you’d like read only operations like getting the list of available pipelines to not require login
  4. Leave Allow Login Authentication disabled unless you’d like to enable the use of username/password based authentication. We recommend using the default bearer token authentication

REST Data Server Settings.png

Getting an Auth Token

By default, the REST Data server requires bearer token authentication. To create a token do the following:

  1. Navigate to Manage | Users
  2. Select an existing or create a new user to assign the API token to
  3. Select API Keys
  4. Select New API Key
  5. Name the key and select Create
  6. Copy the API Key before navigating away. API keys are only shown once

API Key Example

API Documentation

The easiest way to explore the API is by opening the swagger documentation using default URL http://localhost:8885/data/doc once the REST Data Server is enabled.

API Trigger Pipelines

For a pipeline to be visible from the REST Data Server, it must have an enabled API Trigger. These pipelines must also use Return and Error stages to control what gets returned to the API caller. Below is a simple example of a pipeline to create a maintenance work order that takes a machineID and message and is exposed over the REST Data Server.

Example API Trigger

Below is an example of using Postman to call this pipeline. Note the payload includes the API Trigger parameters, and the bearer token was copied into the Authorization section of postman.

Postman Example

Controlling HTTP Response Codes

In some cases it’s important to control the HTTP response code returned to the caller. To do this use a Transform stage and set the event metadata as shown.

Note that Return stages will return 200 by default, and pipeline errors will return 400.

HTTP Error Code.png