Setting Up API Gateway

First published on: 02/21/2024/8:44 pm

 

 

Saltbox API Gateway supports customized APIs that integrate securely and reliably with any number of systems.

 

Workflows define the behavior of each API Gateway route.

 

This walkthrough assumes you're familiar with workflow setup and configuration. If you need a refresher, tutorials are linked below.

 

Overview

Once you've configured a project to enable API Gateway support (outlined below), you can set up API routes by adding workflows.

 

A workflow can be included in or excluded from the API, and you can set up additional workflows to perform asynchronous tasks that aren't available via the API directly. For example, a secondary workflow can perform nightly data cleanup, a supporting workflow can send an email report every hour, etc.

 

Each API route is created by setting up a workflow. When configured, an API route is available to authorized third-party systems or tools, such as Postman.

 

Request data sent to the API route will trigger the workflow, allowing that data to be processed using the workflow design. Requests are real-time, and the workflow must respond within 30 seconds (due to technical limitations). That way, best practices prioritize performance, as the walkthrough below notes.

 

When the workflow is complete, a response is generated using the configured output message resulting from the workflow. This is specifically a message called output, as other messages may be used within the workflow for processing the request message data.

 

Step 1: Before you start…

  • Ensure your tenant is licensed to access API Gateway functionality. Contact your Saltbox implementation consultant if you are unsure.
 

Step 2: Project setup (Enabling the API)

A project is the base for a new API. To get started with API Gateway:

 

  • Create a project.
    • This project will be available as an API and accessible by authorized third-party systems.
  • Enable API Gateway access for the project. This allows workflows to be configured and accessed as API routes.
    • Go to Project Settings > API Gateway.
    • Check the option "Enable AWS API Gateway access for the project".
    • Save updated settings.
    • Once saved, API keys are manageable as outlined in the Technical Reference for API Gateway page.
  • For the first-time setup, generate a new API key with the appropriate expiry date.
    • Use the quick-copy link to copy the key.
    • Use that key to authenticate connections to API Gateway using third-party tools like Postman.
 

Video: Manage Saltbox API Gateway Keys

 
 
 

Step 3: API route workflow setup

To set up a new API route:

 

  • Create a new workflow. 

  • Go to Workflow Settings and check Enable API Gateway Access (marker 1 below).

    • The project must first be configured as outlined in step 2 above.

  • Save settings to enable the route.

 

 

Once the workflow’s API Gateway access is enabled, the Realtime API route URL will be displayed.

 

Use this URL in a third-party app like Postman to securely connect to the API.

 

Copy the URL as needed using the quick-copy icon (marker 2 below).

 

 

You can access this API route, but it won't perform tasks yet.

 

At a high level, the next steps are:

 

  • Configure the workflow trigger.

  • Create and refine the workflow design.

 

3.1: Workflow trigger setup

A workflow trigger defines the basic format of the request body data expected by the workflow. (For general details about Workflow trigger setup, see Workflow Trigger Setup.)

 

Configure API Gateway trigger settings as follows:

 

  • Connector: Connector.Integration.Core

  • Connection Config: (leave blank)

  • Source: Event Workflow Trigger

  • Source Settings

    • ID Path: (leave blank - it will be configured in a future step)

  • Raw Message Contents

    • Message Format: Select the expected message format, such as JSON or XML

    • Other settings may be left as default

 

Once the settings are configured, Save the workflow trigger to apply them.

 

Restart the project engine if it was already started.

 

3.2: Workflow design setup

Workflow design follows the same basic process as other integrations.

 

 

You'll find best practices for designing an API Gateway workflow, including:

  • Keep request and response data succinct.

    • File sizes less than 100 KB are recommended to avoid response time delays.

    • Design the workflow to require as little data as necessary to generate the desired response.

  • Design the workflow for speed.

    • Workflows must respond within 30 seconds, or the request will time out.

    • Where supported, perform targeted query-based data selection rather than time-costly object retrieval.

  • Test with various sample data sets (success and failure) using a tool such as Postman.

  • Optimize the time-costliest actions first.

    • A modest improvement on a long action provides better overall workflow optimization.

 

3.3: Response data format setup

Response data is generated using the output message.

 

To create the output message, use Visual Data Mapper. You can generate this using the Saltbox Core Connector’s “Transform Object” action or any other action that generates an output message.

 

You should prioritize the visual data map for time efficiency. Only map the fields necessary to achieve the response data (or data needed in an interim step).

 

 

  • Enable Apply Map (1).

  • Set the Map Type to “Map” (2).

  • Set the Map Output to the desired format (3).

  • Enable Save Action Output to Workflow Messages to save the mapped results.

  • Set the Message to Write To to “output”.

 

3.4: Supported data formats

API Gateway supports request and response data in JSON or XML formats (marker 3 above).

 

Configure the workflow trigger to convert the request data into workflow-compatible message data.

 

Configure an output message named output to produce the API route’s response data.

 

Ensure the output type is set to the format (JSON or XML) that’s expected by the requesting application.

 

Step 4: Testing

The outline below uses Postman, although you could use any API tool.

 

  1. In Saltbox, go to "Workflow Settings" and copy the Realtime API URL using the quick-copy button.

  2. Create a new POST request using Postman. Paste the API URL into the Postman address bar.

  3. In Saltbox, go to Project Settings > API Gateway and copy the API key using the quick-copy button.

  4. Configure a header parameter by opening the Postman headers tab and adding the parameter name X-Api-Key.

  5. Paste the API key in Postman as the X-Api-Key value. NB X-Api-Key is case sensitive.

  6. Configure request data by opening the Postman body tab and selecting raw as the format. Configure the specific format as required by the request data being submitted (in this case, JSON). Provide the data that will be sent to the API for processing.

  7. Send the request.

  8. A response will be displayed in Postman. If the workflow was successful, the API will respond with a 200 status code and response data. If the workflow was unsuccessful, you'll get a status code (see API Gateway Error Codes).

     

You can view the processed message with the Saltbox Message Trace feature.

 

Inspect request data by expanding the status section (marker 1 below) and opening the data using rawMessage.xml for raw request data (marker 2 below) and message.xml for pre-processed workflow-compatible data (marker 3 below).

 

 

Inspect response data by expanding the last action to modify the “output” message (typically the last action in the workflow).

 

Data retention policies may apply, which affect how long (and even if) request/response data is available.

 

 

Previous

Next

  

First published:  02/21/2024/8:44 pm

Last modified: 03/25/2025/12:56 pm

On this page

-