Using the Flow API to liberate your information

Flow has a secured yet open API that allows you to read both your data and your configuration. This is particularly useful when you want to "bridge" your information to other systems, such as a data lake, an ERP system, or even to your plant's SCADA.

To view detailed documentation on the Flow API, access the /api endpoint on your Flow server. For example, if your Flow server and port are configured as "MyFlowServer" and "8000" respectively, open the following link in your web browser: http://MyFlowServer:8000/api

The Flow Public API documentation will open, similar to the below.

An alternate way to open the above URL is to navigate to the Deployment tab in the Config tool, expand the Flow Server node, then right-click on the Flow API node and select Tasks > Open (or you can Copy Link and paste it into your browser)

The documentation webpage explains how to use the various endpoints. On the webpage, you can even test API calls. For example, if you scroll down to the config/calendars endpoint, and click on it to expand the documentation:

Select the "Try it out" button. Note the section called "Parameters" - in this section you can specify any parameters that need to be populated with the API call. In the case of the config/calendars endpoint, there are no parameters that need to be specified. 

Select the "Execute" button. This will initiate the API call.

Note the successful response, indicated by code 200. Also, the Response Body documents what that specific endpoint returns, in this case, a JSON payload with an array of "errors" (there are no errors here) and an array of "calendars". Not that this Flow instance has one calendar, named "Production" and this has an ID of 1. Let's use that ID in another endpoint that requires the Calendar ID to be passed in as a parameter, namely, the config/calendars/{id}/shifts endpoint

Note that this endpoint has a required parameter named "id". Specifically, this is a Calendar id, as explained in the Description. Let's enter the value of 1 as our calendar id, since we know from our query of the calendar endpoint that the Production calendar has an id of 1. Hit the "Execute" button.

Note the response body: this endpoint returned a JSON payload with an array of "errors" (no errors in this example) and an array of "shiftSchemes". Here, the "shiftSchemes" object contains the shift "id", the "dateTime" from which each shift is valid, and metadata of the shift.

What if the API call returns an error?

When executing an API call, the Response Code may be used to determine whether the call was successful or not. A 200 response code indicates a successful call, with data returned. 

A common "failure" response code is 401, which indicates that the call is not authorized. The Flow API uses Bearer Tokens to ensure that a call is authorized. If the bearer token has not been provided with the API call (or an incorrect token is provided), the Flow server will return a 401 error, similar to the below

To resolve this issue, you need an updated bearer token. To generate a bearer token, follow the steps outlined in the article What is a Flow Server Key, how do I create one, and where do I need to use it?

The bearer token is the "Server Key" that is generated when following the steps in the referenced article.

If you are testing the API calls using your browser and you get a 401 response code, this indicates that your session is not logged in - to log in again, open a new browser tab and navigate to the Flow server's home page, for example, http://MyFlowServer:8000

Then follow the instructions in the article Configuring your User Profile on the Flow Server using your web browser to log in. After you have logged in, you can return to the browser tab where the API documentation endpoint is open and execute the API call again.

Using an API testing platform like Postman

You can generate a Postman "collection" by using the link at the top of the API documentation webpage, similar to /api/v1/docs.json 

Click on this link which will open the documentation in a JSON format in a new browser tab, similar to the below.

Save this file from your browser to a location on your computer or network.

Follow the steps in Postman to Import this file from the location where you saved it to.  This will create a collection in Postman of all the available Flow API endpoints.

As a suggestion, configure the following Postman "variables" on the folder in the collection named "Flow API":

On the "Flow API" folder, select the Authorization Tab and configure the Type to be "Bearer Token" and set the Token field to {{Flow}}

This will reference the variable named "Flow" that you configured above, where you pasted the Flow Server Key.

Navigating through the various endpoints in the Postman collection, you'll note that all endpoints begin with the variable {{baseUrl}}. This variable in turn references the other variables that you created above.