# API collections management

SUMMARY

  • API collections in Workato are groups of endpoints with a common access pattern.
  • Collections contain either API recipe endpoints, which are endpoints built from API recipes ("build your own backend"), or API proxy endpoints, which forward requests to an API backend ("bring your own backend").
  • Workato offers machine-readable documentation (OpenAPI v2.0) for endpoints in an API collection. The documentation can then be synced to Postman.

An API collection consists of API endpoints with a common access pattern, so that they can be managed together. For example, a set of Salesforce endpoints that will be called by recipes used by the Sales team should be grouped together into an API collection.

The API collections page displays all API collections within a workspace. To access the API collections page, navigate to Tools > API platform > API collections.

A collection can include either API proxy endpoints or API recipe endpoints. Collections containing API proxy endpoints have an API proxy label.

API collections page API collections page

# Collection types

There are two types of API collection:

# What is an API recipe collection?

An API recipe collection is a set of endpoints that are each built from an individual API recipe. One recipe corresponds to one endpoint.

With a collection of API recipes, you can make powerful API endpoints available to internal users (such as other team members) and external users (such as your organization's end users, even if they don't have a Workato account). Other recipes can even make use of API recipe collections.

By grouping related API recipe endpoints into a collection, you can easily manage access to the endpoints.

# What is an API proxy collection?

An API proxy collection is a collection of proxy endpoints, each of which acts as an intermediary between an API client and API server. When you send a request to a proxy endpoint, Workato simply forwards that request to an endpoint within the backend API.

You can use proxy endpoints to add a layer of security and control to an internal API. Your teammates and external collaborators send requests to the secure proxy endpoint instead of directly to your backend API. This also allows you to benefit from the API Platform's monitoring and access control features.

# Choosing a collection type

The type of collection you choose to create depends on your use case.

  • Choose an API recipe collection when you want to build your own backend. In this case, you'd create an API recipe containing all the required logic to fetch and/or process data from other sources (such as external APIs). For example, a recipe could use the Salesforce API to search for opportunities matching a particular name, and if it finds no matches, it could then create the opportunity according to a specific configuration.

    API recipe collections are ideal in this scenario for the following reasons:

    • API recipe collections are optimized for high-value jobs.
    • API recipes jobs are subject to concurrency limit
    • With API recipe collections, you have the flexibility to highly customize how you fetch and process data.
  • Choose an API proxy collection when you want to bring your own backend. When a proxy endpoint receives an incoming request, Workato simply forwards the request to your existing API backend.

    API proxy collections are ideal in this scenario for the following reasons:

    • API proxy collections are optimized for high-volume, low-cost jobs.
    • Proxy jobs are executed with minimal latency.
    • Proxy requests are not subject to concurrency limits.
    • With API proxy collections, customization options are limited since the main function is to forward requests.

The right balance of recipe-based and proxy-based collections can help you optimize your API platform usage.

# Creating an API recipe collection

COLLECTION TYPES

Not sure whether you need to create an API recipe collection or API proxy collection? See Choosing a collection type.

# Prerequisites for API recipe collections

  • Create a project, if you haven't already.
  • Create a folder in the project and add one or more API recipes to it. Any new API recipes added to the folder will be included in the collection automatically. We recommend that you organize related API recipes together.

# Create the API recipe collection

1

Navigate to Tools > API platform > API collections.

2

Select New collection.

3

In Choose collection type, select API recipe collection.

Select API recipe collection Select API recipe collection

4

In Choose a configuration type, specify how you want to configure your recipe collection:

  • Use existing recipes

  • Select the recipe folder from the picklist. Any API recipe in this folder will be linked to a new endpoint.

  • Import OpenAPI Specification

  • Upload a JSON or YAML OpenAPI specification file, or enter the URL of the specification.

5

In Customize endpoints, check the box next to each endpoint you want to add to the collection. You can select Edit details next to an endpoint to configure the following information:

  • Endpoint name

  • Enter a descriptive name for the recipe endpoint.

  • Endpoint path

  • Define a path for this endpoint. It can include path parameters. Ensure the endpoint path conforms to these guidelines.

  • HTTP method

  • Select the HTTP method to use for the endpoint.

  • Time-to-live period

  • Only required when you toggle Cache response. Specify the time in seconds that a response is stored in cache before it is refreshed or deleted. The maximum is 3600 seconds.

  • Request timeout

  • Only required when you toggle Customize timeout. Customize the time that a request is given to complete. The default value is 30 seconds and the maximum value is 240 seconds.

Customize API recipe collection endpoints Customize API recipe collection endpoints

6

In Set collection details, enter the following information:

  • Collection name

  • Enter a descriptive name for the API collection.

  • Version

  • API collections are versioned using a unique 1-10 character version identifier. Collections with the same name but different versions are distinct objects.

  • Description (optional)

  • Enter a short description of the API collection.

7

Select Create collection. Workato creates the collection and shows the number of endpoints added.

Create API recipe collection Create API recipe collection

8

Select View API collection.

9

By default, all new endpoints are inactive. You must activate an endpoint to allow other recipes or apps to call it.

Activate the desired endpoints in your new collection by toggling Inactive:

Activate API endpoint in a collection Activate API endpoint in a collection

For more information about activating endpoints, see Activating or deactivating an endpoint.

10

Enable specific users or apps to access this collection by assigning the collection to a client's access profile. Learn how to create a new access profile.

# Creating an API proxy collection

COLLECTION TYPES

Not sure whether you need to create an API recipe collection or API proxy collection? See Choosing a collection type.

# Prerequisites for API proxy collections

  • Create a project, if you haven't already.
  • In the project, create an HTTP connection to forward requests to.

# Create the API proxy collection

1

Navigate to Tools > API platform > API collections.

2

Select New collection.

3

In Choose collection type, select API proxy collection.

Select API proxy collection Select API proxy collection

4

In Choose an HTTP connection to forward requests to, select an existing HTTP connection from the list or create a new one. You can select Details to view a connection's configuration.

Choose HTTP connection to forward requests to Choose HTTP connection to forward requests to

SUPPORTED AUTHENTICATION TYPES

Currently, API proxy collections support the following HTTP connection authentication types:

  • No-auth
  • Query
  • Basic
  • Header

If you choose a connection with an unsupported authentication type, Workato displays an Unsupported authentication type error message.

5

In Choose a configuration type, specify how you want to configure your proxy collection:

  • Import OpenAPI Specification

  • Upload a JSON or YAML OpenAPI 3.0 specification file, or enter the URL of the specification. Workato will use the OpenAPI specification to automatically set up the schema for the endpoints you add in the next step.

  • Manual configuration

  • Workato will create an empty collection you can add endpoints to later. For details, see Set up schema.

6

Only if you imported an OpenAPI specification: In Customize endpoints, check the box next to each endpoint you want to add to the collection. You can select Edit details next to an endpoint to configure the following information:

  • Endpoint name

  • Enter a descriptive name for the proxy endpoint.

  • Endpoint path

  • Define an endpoint path to be appended to both proxy and target base URLs. It can include path parameters. Ensure that the endpoint path conforms to these guidelines.

  • HTTP method

  • Select the HTTP method to use for the endpoint.

  • Request timeout

  • Only required when you toggle Customize timeout. Customize the time that a request is given to complete. The default value is 30 seconds and the maximum value is 240 seconds.

Customize API proxy collection endpoints Customize API proxy collection endpoints

7

In Set collection details, enter the following information:

  • Project

  • The API collection is only available to members who have access to the specified project.

  • Collection name

  • Enter a descriptive name for the API collection.

  • Version

  • API collections are versioned using a unique 1-10 character version identifier. Collections with the same name but different versions are distinct objects.

  • Description (optional)

  • Enter a short description of the API collection.

8

Select Create collection. Workato creates the collection and shows the number of endpoints added.

Create API proxy collection Create API proxy collection

9

Select View API collection.

10

By default, all new endpoints are inactive. You must activate an endpoint to allow other recipes or apps to call it.

Activate the desired endpoints in your new collection by selecting an endpoint's Inactive toggle:

Activate API proxy endpoint in a collection Activate API proxy endpoint in a collection

For more information about activating endpoints, see Activating or deactivating an endpoint.

11

Enable specific users or apps to access this collection by assigning this collection to a client's access profile. Learn how to create a new access profile.

# Editing an API collection

After you create an API collection, access its overview by navigating to Tools > API platform and then selecting the collection. From here, you can add, remove, edit, or test endpoints that are available within the collection.

API collection overview API collection overview page

# Configuring collection settings

You can configure options for an API recipe or proxy collection by navigating to its Settings tab and then selecting one of the following interfaces:

# Collection settings

Keep your collections organized by assigning version tags and descriptions.

  • Version number

  • API collections are versioned using a unique 1-10 character version identifier. Collections with the same name but different versions are distinct objects.

  • Description

  • A short description of the collection.

API collection settings tab API collection settings tab

# URL settings

Customize the URL and path for this API collection. Available settings differ according to the type of collection.

WARNING

oauth2 is a reserved namespace. A collection path cannot begin with oauth2.

API RECIPE COLLECTION
  • Collection path
  • Customize the URL path specific to this API recipe collection. For example, you can use this field to differentiate collections for sales, marketing, or HR.

    Note that the domain and path prefix are configured through the API Platform's Settings tab, not the collection settings.

API recipe collection URL settings API recipe collection URL settings

API PROXY COLLECTION
  • Collection path

  • Customize the URL path specific to this API proxy collection. The path is updated in the Proxy URL preview as you type.

    For example, you can use this field to differentiate collections for sales, marketing, or HR.

    Note that the domain and path prefix are configured through the API Platform's Settings tab, not the collection settings.

  • Target HTTP connection

  • Select Switch to choose a different HTTP connection. The Target URL preview is updated accordingly.

API proxy collection URL settings API proxy collection URL settings

# Sharing

By default, new collections are hidden from the API library. The UI displays the message Hidden from this workspace's API library:

API collection is hidden from the API library API collection is hidden from the API library

If you select Show in API library, anyone in your workspace can find the collection and request access to it. The UI displays the message Discoverable in this workspace's API library and includes a list of who can see the collection.

API collection is discoverable in the API library API collection is discoverable in the API library

To hide the collection again, select Hide from API library.

# Sync to Postman

After your API collection is successfully deployed and live, it is time to consider adoption of this API beyond the original client. Increase visibility of any API collection by synching it to your Postman (opens new window) workspace. There, you can make use of the internal and external portal to drive adoption.

1

Open the API collection that you wish to sync.

2

Navigate to Settings tab > Sync to Postman. Click on Sync to Postman to get started.

3

You will need to connect to your Postman instance and workspace. Select an existing Postman connection or create a new one.

4

Configure where your API collection will be saved in Postman.

  1. You can create a new API with New API in Postman.
  2. You can save this API collection in an existing Postman API

Saving API collection into an existing Postman API

If you are saving into an existing Postman API, you must provide a version name. Workato recommends that you give this a distinct version name. You may choose to overwrite an existing version.

5

Click Sync API collection to complete the sync.

Workato will automatically send the OpenAPI Specification of this API collection to Postman and save it as a new or existing Version of the chosen API in Postman. This API version can now be configured for publishing in Postman to your developer community.

When the API is updated, you can click Refresh sync to update the Postman API with the latest version of the API collection.

# Machine-readable documentation (OpenAPI)

Video guide: How to build APIs faster with OpenAPI

The API collection page has a link in the upper-right corner labeled Download OpenAPI spec. The link gives you access to a downloadable file that contains documentation for all the endpoints within the collection, in a format that can be used by tools such as Postman. This format is called OpenAPI, also known as Swagger.

Currently, Workato supports exporting OpenAPI version 2.0 (opens new window) of the specification through the Download OpenAPI spec button.

Note that Workato supports OpenAPI version 3.0 (opens new window) when importing an OpenAPI specification into an API recipe collection or API proxy collection.


Last updated: 9/14/2023, 9:26:48 AM