API

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

This article explains how to use API binding. For troubleshooting, see Troubleshooting API Binding.

Define a Subdomain

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

Click the edit button against the Environment you would like to run the Workflow under in order to set a subdomain and optionally a list of allowed origins.

Allowed Origins only needs to be specified if you intend to invoke Flowgear from a client that applies Cross-Origin Resource Sharing https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), for example when invoking Flowgear from a web app.

A unique subdomain must be specified per Environment. After saving settings, open a ticket with Flowgear to request the required DNS changes be made.

Note that the Enterprise plan permits a completely whitelabelled domain (e.g. api.company.com), other plans permit a subdomain only (e.g. `company.flowgear.net``).

Create a RESTful URI template for a Workflow

In the Workflow Design Pane, click the Workflow Settings button in the command bar 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 are encapsulated in braces.
• Variable sections in the querystring component should take the form identifier={variablename}.

For example, for the URL /contacts/{id}?top={limit}, Variable Bar Input Properties for id and limit should be added to the Workflow.

Authentication

All calls must be authenticated using an API Key. Flowgear provides Token-based authentication.

Working with HTTP Request and Response data directly

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

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 approach can also be useful in the following scenarios:

• Emulating 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

Sample Workflow - 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