API v1

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

Enterprise API - publish a suite of APIs for your customers and suppliers that are not tightly coupled to your underlying systems.
Webhook Receivers - act on real-time 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 an Environment Hostname

Open Site Settings by selecting Settings → Site settings.

Click Edit Environment for the Environment in which you want to run the Workflow. Set a Host name and, if required, Allowed origins.

Specify Allowed origins only if you intend to invoke Flowgear from a client that applies Cross-Origin Resource Sharing, for example, a web app.

Each Environment must have a unique hostname. After saving the settings, open a ticket with Flowgear Support to request the required DNS changes.

Enterprise subscriptions can use a custom Production domain (for example, api.company.com) and supply its TLS certificate. Other subscriptions use a Flowgear subdomain (for example, company.flowgear.net). Confirm the available hostname and certificate options with Flowgear Support.

Create a RESTful URI Template for a Workflow

In the Workflow designer, open Workflow settings.

Enable HTTP binding, select an HTTP binding method, and enter an HTTP binding path.

Note the following:

The URI must start with a slash (/).
Variable sections of the URI are enclosed in braces. You must have already created Variable Bar inputs that match these names.
For query-string parameters, use the form identifier={variableName}.

For the URL /contacts/{id}?top={limit}, add Variable Bar input Properties named id and limit to the Workflow.

Authentication

All calls must be authorized by an API Key that permits the Workflow in the same Environment. Use Token Authentication for service callers or Cookie-based Authentication for calls made by embedded Flowgear Apps on behalf of authorized signed-in Console users.

Working with HTTP Request and Response Data Directly

By default, the Flowgear API reads top-level primitive inputs from a JSON request body and returns Workflow outputs as JSON key:value pairs.

You may also work directly with the raw HTTP request and response payloads, as well as certain HTTP request and response headers, if you require more control. This approach can be useful in the following scenarios:

Emulating a third-party API to enable Flowgear to act as an intelligent proxy, for example, making the endpoint behave like a SOAP service.
Returning other content types, for example, XML, an image, or a document instead of JSON.

See Configure Variable Bar for the available HTTP request and response Properties.

To use these Properties, include them in the Variable Bar.

You can use HTTP request and response Properties independently:

Consume the raw HTTP request by adding FgRequestBody to a Variable Bar.
Emit a raw HTTP response by adding FgResponseBody to a Variable Bar.
Add both FgRequestBody and FgResponseBody to 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.