The Flowgear API enables you to bind your own subdomain to a Flowgear Site as well as a RESTful path to each Flowgear Workflow. The API also optionally allows you to expose a service (as a Workflow) that can engage directly with the raw HTTP request (POST) payload and/or the raw response payload.


This page deals with the current Flowgear API. See API (Legacy) for documentation on the Legacy Flowgear API.

Binding a Subdomain

Open the Site Detail Pane by clicking your Site name in the left-hand menu and then choosing Edit this Site.

Under Custom Domain provide a sub-domain. Note that if your Site is running in our US or Europe environments, the base domain will be flowgear.net. For the ZA environments, the base domain will be flowgear.io.

If you intend to invoke Flowgear from a client that applies Cross-Origin Resource Sharing (CORS - https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), provide a list a allowed origins in the Allowed Origins textbox or provide * to permit all origins.

After saving changes, a DNS record will be created. An error will be presented if the syntax of the specified Subdomain is invalid or the chosen Subdomain has already been used.

Allow a few minutes for the record to propagate before attempting to use. Check the name resolves with a ping before attempting to access. On Windows, use ipconfig /flushdns to force a refresh of the record.


Site-detail-subdomain.png


Creating a RESTful URI template for a Workflow

In the Workflow Design Pane, click the Workflow Settings button (cog icon) to access the Workflow Settings Pane.

Under API Binding, select an HTTP method and provide a RESTful path template.

Note the following:

  • The URI must start with a slash (/).
  • Indicate variable sections of the URI by encapsulating identifiers in curly braces. You must have already created Variable Bar inputs that match these names.
  • Variable sections in the path may simply be placed into the URI.
  • Variable sections in the querystring component should take the form identifier={variablename}. In this example, variable is static and the value passed in in the place of variablename will be passed to the Variable Bar variable variablename. The example below shows a URI template containing the field id. A Variable Bar input property named id should be added to the Workflow.


Workflow-settings-bind-uri.png


Example Endpoints

Endpoint Template Sample URL Note
GET https://yourcompany.flowgear.io/reports/revenue/annual/{year} GET https://yourcompany.flowgear.io/reports/revenue/annual/2020 The value 2020 passed in place of year will be set on a Variable Bar variable called year.
GET https://yourcompany.flowgear.io/reports/revenue/?name={reportName} GET https://yourcompany.flowgear.io/reports/revenue/?name=specialreport The value specialreport will be passed to the Variable Bar variable reportName.

Authentication

The Flowgear API supports Basic HTTP Authentication as well as session-based authentication.


Basic Authentication

  • When an endpoint is accessed through the browser for the first time, an HTTP 401 Unauthorized response will be returned which will cause the browser to present a login dialog. Once valid credentials have been captured, the browser will retain the authentication data for the remainder of the session
  • To programatically provide Basic Authentication, add the following HTTP Header to the request:


Authorization: Basic {base64sequence} where {base64sequence} is a Base64 encoded representation of {username}:{password}.


For example, myname@mycompany.com:mypassword becomes: bXluYW1lQG15Y29tcGFueS5jb206bXlwYXNzd29yZA==.

The full HTTP Header should be provided as Authorization: Basic bXluYW1lQG15Y29tcGFueS5jb206bXlwYXNzd29yZA==



Session Authentication

Add an authentication token to the querystring for the request using the identifier auth. For example:


yourcompany.flowgear.io/reports/revenue/?name=specialreport&auth=9efe0254-bf16-4c2f-9278-8fa121aa92aa


The authentication token can be temporarily obtained from within the Flowgear Console. Open the Account Pane, then select About and copy the value in the Session ID Textbox. To programatically obtain an authentication token, use this request template:


GET https://api.flowgear.net/users/{username}/auth/?password={password}


If the supplied username and password are correct, an authorisation token will be returned as a JSON string. For example:


"9efe0254-bf16-4c2f-9278-8fa121aa92aa"


Working with HTTP Request and Response data directly

By default, the Flowgear API will expect inputs to be provided as JSON key:value pair list and will return outputs as a key:value pair list.

You may also engage directly with the raw HTTP request and response payloads as well as certain HTTP request and response headers if you require more control over the request and/or response. This technique is useful in the following scenarios:

  • Mimicking of a third party API to enable Flowgear to act as an intelligent proxy. For example, you may wish to have the endpoint behave like a SOAP service
  • Serving back other content types. For example, you may wish to serve back XML, an image or a document instead of JSON


Refer to Configure Variable Bar for a list of HTTP request and response properties that are available.

To use these properties, simply include them in the Variable Bar. Note that you do not have to work with both HTTP request properties as well as HTTP response properties. For example:

  • You may consume the raw HTTP request by adding the FgRequestBody to a Variable Bar or
  • You may emit a raw HTTP response by adding FgResponseBody to a Variable Bar or
  • You may add both FgRequestBody and FgResponseBody to both consume and emit raw data

Code Samples

https://flowgear.me/s/Di0pBLU - A Sample Workflow illustrating how to bind a GET request

CSharp API Example - Uses HttpWebRequest with statically defined request and response interface classes. Requires Json.NET

CSharp API Simplified Example - A simple C# example that can be used to send and receive payloads as strings.

PHP API Example - Illustrates how to call a Flowgear workflow via REST API using cURL

© 2010 - 2016 Flowgear