15. Building API's

So far we've consumed third party API's but a key feature in Flowgear is the ability to publish any Workflow as an API. In this section, we'll walk through how to set up your Site and then create and publish a Workflow as an API.

Common use cases include:

Delivering an Enterprise API that wraps an organization's data structures and business logic to authorized third parties like customers, vendors and partners
Receiving and acting on webhooks that are notifications of activity in third party apps or services
Mobile Backend as a Service or Web App Backend as a Service
An intelligent proxy that adds business logic, modernizes, extends or meters an internal or legacy service.

Building a REST Service

Assigning a Hostname

Each Environment in a Flowgear Site can have a unique hostname (domain) associated with it. You can view this information from → Edit Site Settings under Environments.

Click ✎ next to an Environment (we'll use the Test Environment) to see the associated host under Hostname.

Under trial accounts, all hostnames are pre-configured and include your tenant key in the hostname.
On paid plans, you can choose a custom sub-domain so that your hostname ends with .flowgear.net.
On certain paid plans, you can specify a completely custom domain. For example, instead of mycompany.flowgear.net, you can specify api.mycompany.com. Note that in these cases, you'll be responsible for making DNS changes and providing Flowgear with a TLS certificate.

Creating an API-Bound Workflow

Flowgear is normally used to publish Workflows as REST API's (although it can also be used to emulate a SOAP service). As we looked at in an earlier section, REST uses the HTTP Method to denote the action to take while the URL is the resource the action should be taken against. REST services also typically use JSON request and response payloads (although Flowgear doesn't enforce this).

From within the Workflow, you'll be able to configure the HTTP Method and the URL template the Workflow will activate for.

When you need to interact with input parameters such as those provided in the querystring of a request or the request body itself, you'll add special input Properties to a Variable Bar Node. Similarly, to send a response body back, you'll add special output Properties to a Variable Bar Node.

Read more about Enterprise API and Special Variable Bar Properties.

Authorizing Access

In order for a consumer to invoke a Workflow, it must provide an API Key that has permission to run that Workflow. You can manage API Keys from the left-hand menu. Keys are scoped to a specific Environment. In other words, each key can only be used to invoke a Workflow under one specific Environment. When managing an API Key, you'll also be able to specify exactly which Workflows are permitted to execute based on that key.

Exercise 20: API Query Service

In this exercise we'll build a Workflow that allows us to query a contact record from a database.

Add Microsoft SQL Query to a new Workflow, rename it Query, connect Start.RunNow → Query.
Create a Connection for Query and use the same credentials given for 09. Working with Databases.
Set Query.Query to select top 1 * from contacts where id = @id.
Add Variable Bar, rename it Inputs.
Add Inputs.id, set this to an Output Property (i.e. Flow Socket on the right-hand side) and set its value to 1.
Add Query.id and connect Inputs.id → Query.id.
Add JSON Convert, connect Query → JSON Convert.
Set JSON Convert.Action to XmlToJson.
Connect Query.ResultXml → JSON Convert.Xml.
Add Variable Bar, rename to Outputs.
Add Outputs.FgResponseBody.

FgResponseBody is a special Variable Bar Property that is used to control the response sent by an API-bound Workflow. Instead of typing the name by hand, click + on the Variable Bar, then click v next to the Property name to see a list of special Properties.

You can read more about these Properties in the Configure Variable Bar article.
Connect JSON Convert.Json → Outputs.FgResponseBody.
Add Outputs.FgResponseHeaders, set it's value to application/json.

FgResponseHeaders allows us to provide the set of headers that should be returned to the consumer. The only required header is Content-Type which advises the consumer of the type of content being returned, known as a mime type.

In this exercise we are going to return a JSON document which uses the mime type application/json.
Open Workflow Settings (just to the right of the Save button)/
Under API Binding, set Method (the dropdown) to GET and the path (where you see /path/to/endpoint) to /contacts/{id}.

We are configuring the Workflow to be bound to the template GET /contacts/{id}. In other words, this is a GET request (information is being retrieved rather than changed) and the location is /contacts/{id}.

{id} is mapped to the id Property in the Variable Bar so when the Workflow runs, the value that was provided will be injected into the id Property there.
Click Copy to copy the URL template to the clipboard, then return to the Workflow Design

Run the Workflow to confirm its executing successfully and then save it.

We will now generate an API key to be used with the Workflow.
Open API Keys from the left hand menu. You can do this in a separate browser tab by clicking while holding CTRL (Windows) or ⌘ (Mac).
In API Keys, click +.
Provide a name in Test and add your Workflow under the Add a Workflow section. If you named the Workflow 20: API Query Service, it should be shown there.
Click Save. An API Key will be generated and shown on screen.

Flowgear only stores a cryptographic hash of these keys rather than the keys themselves. If you lose the key, you'll need to generate a new one by clicking Regenerate.
Open a new browser tab and paste in the URL template you copied from the Workflow design. Replace {id} out with a number - for example 2.
Add ?auth-key= to the end of the URL, followed by the API Key shown under Primary Key.

Your full URL should look like this:

https://api-test-trialabcd.flowgear.net/contacts/2?auth-key=longapikeytexthere

Open the URL to confirm you're receiving a JSON document back containing the details of the contact specified in the querystring.

Save and run your Workflow, then click Submit Exercise to grade it.

Exercise 21: API Update Service

In the previous exercise, we built an API that queries data from an underlying source. In this exercise, we'll accept data from the consumer (i.e. the party invoking the API) and store it in an underlying service.

Add File Write to a new Workflow, connect Start.RunNow → File Write.
Create and assign a Connection to File Write that uses your locally installed DropPoint.
Add Variable Bar, rename it Inputs.
Add Inputs.FgRequestBody and set it's value to the value below:
```
 {
 	"somefield": "somevalue"
 }
```
Connect Inputs.FgRequestBody → File Write.Content.
Set File Write.Path to a location in which the file can be created - for example c:\temp\test.json.

For this exercise, we're hardcoding a file name so the content will be replaced each time the Workflow runs.

In a real-world scenario, we could add a filename Property to the querystring and then dynamically compose a path that includes the filename Property.

This would allow us to create a file with a name specified by the consumer. Bear in mind that with this approach, it would be important to test that only expected characters are provided in the file name. For example, if the consumer provided a file name ..\somefile.json, it would resolve to c:\somefile.json. In other words, it would cause a file to be created outside of the folder we expected.
Add Formatter.
Set Formatter.Expression to the following:
```
 {
 	"result": "ok"
 }
```
Add Variable Bar, rename it to Outputs.
Add Outputs.FgResponseBody and Outputs.FgResponseHeaders.
Connect Formatter.Result → Outputs.FgResponseBody.

The Formatter is used to send a hardcoded success response back to the API. In a real-world scenario, we'd build a response based on whether or not data was ingested successfully.
Set Outputs.FgResponseHeaders to Content-Type: application/json.
Open Workflow Settings, set the HTTP Method to POST and the URL template to /contacts.

Run the Workflow and confirm a file has been created at c:\temp\test.json.

If you receive a DropPoint whitelisting error, you need to adjust your whitelisting rules to allow the file to be created. See DropPoint for more information.

Save your Workflow at this point.
Return to the API Key that you created in the previous exercise and add this Workflow under the Add a Workflow section. You may need to refresh the page to see the new Workflow if you've left the tab open. Save the API Key after making this change.

Save and run your Workflow, then click Submit Exercise to grade it.

Exercise 22. API Test

In the previous exercise, we invoked a Workflow from a browser. This is a convenient way to test because when you open a URL from a browser address bar, the browser will use the HTTP Method GET.

However, for this Workflow we need to send a POST Request. We could achieve this by using a Web Request 2 Node in a new Workflow but it would be best to use a REST Request.

In this exercise, we'll obtain an OpenAPI definition of our REST Service that we can then use to invoke our API using REST Request.

Go to the Workflows Pane and click the ↓ button on the right-side, choose Download OpenAPI Definition, save the file to your computer and open it in Notepad.
Add REST Request to a new Workflow.
Create a new Connection for REST Request.
In the Connection, set OpenApiDocument to the content of the document you downloaded and opened in Notepad.
Set Url to the hostname of your Site for the Test Environment. For example https://api-test-trialabcd.flowgear.net.
Set AuthType to Bearer.
Set AccessToken to the API Key you generated earlier. If you have lost the Key, go back to the API Key screen and click Regenerate.
Save the Connection, then click Refresh Metadata (you may need to scroll down to see this button).
Back in the Workflow, click v → Choose Sample on the REST Request Node and you should see the two API Workflow exercises.
Change the value of somefield to someothervalue in REST Request.Request.
Choose the 21. API Update Service Node Sample.

Run the Workflow and confirm that the ResponseCode Property shows 200.

Save your Workflow and run it, then click Submit Exercise to grade it.