All Collections
API
API
API
Daniel Chilcott avatar
Written by Daniel Chilcott
Updated over a week ago

Any Flowgear Workflow can be published as a REST API. Common applications for this capability include:

  • Enterprise API - publish a suite of API's for your customers and suppliers that are not tightly coupled to your underlying systems

  • Webhook receivers - act on realtime events in third party applications and services

  • HTTP proxies - intercept calls to legacy SOAP or REST endpoints to embed additional business logic or interface with multiple underlying systems

  • API mediation - create mashups of internal datasets and optionally control caching to reduce overhead on those systems


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.

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.

Example Endpoints

GET https://yourcompany.flowgear.io/reports/revenue/annual/{year}

Example: GET https://yourcompany.flowgear.io/reports/revenue/annual/2020

The 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

All calls must be authenticated. Flowgear provides the following authentication options:


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

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

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

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

Did this answer your question?