# 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 v3.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 Platform > 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

# Collection types

There are two types of API collections:

API proxy collection
API recipe collection

# What is an API proxy collection?

An API proxy collection is a collection of proxy endpoints. Each endpoint acts as an intermediary between an API client and API server. When you send a request to a proxy endpoint, Workato 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.

# 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.

# Choosing a collection type

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

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.
Choose an API recipe collection when you plan to build your own backend. To do this, you must create an API recipe containing the required logic to fetch and/or process data from other sources (such as external APIs). For example, your recipe could use the Salesforce API to search for opportunities that match a particular name, and if the search returns 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 a concurrency limit.
- API recipe collections provide the flexibility to highly customize how you fetch and process data.

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

# 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

Navigate to Platform > API platform > API collections.

Select New collection.

Use Choose collection type to select API proxy collection.

Select API proxy collection

Use Choose an HTTP connection to forward requests to 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

SUPPORTED AUTHENTICATION TYPES

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.

Use Choose a configuration type to specify the configuration you plan to use in your proxy collection:

Import OpenAPI Specification
Upload a JSON or YAML OpenAPI 3.0 (opens new window) specification file, or enter the URL of the specification. Workato uses the OpenAPI specification to automatically set up the schema for the endpoints you add in the next step.
Manual configuration
Workato creates an empty collection you can add endpoints to later. For details, see Set up schema.

Only if you imported an OpenAPI specification: Go to Customize endpoints and select the checkbox next to each endpoint you plan 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

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.

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

Create API proxy collection

Select View API collection.

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

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

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.

# Creating an API recipe collection

COLLECTION TYPES

Not sure whether you should to create an API proxy collection or an API recipe collection? Refer to 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. New API recipes added to the folder are included in the collection automatically. We recommend that you organize related API recipes together.

# Create the API recipe collection

Navigate to Platform > API platform > API collections.

Select New collection.

In Choose collection type, select API recipe collection.

Select API recipe collection

Use Choose a configuration type to specify the configuration you plan to use for your recipe collection:

Use existing recipes
Select the recipe folder from the picklist. API recipes in this folder are linked to a new endpoint.
Import OpenAPI Specification
Upload a JSON or YAML OpenAPI 3.0 (opens new window) specification file, or enter the URL of the specification.

Go to Customize endpoints and select the checkbox for each endpoint you plan 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

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.

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

Create API recipe collection

Select View API collection.

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

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

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.

# Editing an API collection

After you create an API collection, access its overview by navigating to Platform > 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 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
URL settings
Sharing
Sync to Postman

# 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

# 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 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 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

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

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

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.

Open the API collection that you wish to sync.

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

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

Configure where your API collection will be saved in Postman.

You can create a new API with New API in Postman.
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.

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.

By default, Workato supports exporting specifications in OpenAPI version 3.0 (opens new window). However, to ensure backward compatibility, Workato also supports exporting specifications in OpenAPI version 2.0 (opens new window). To export a specification in version 2.0, add the query parameter oas_ver=2 to the download URL. For example:

https://app.workato.com/doc/service/collection-name/swagger?api_group_id=123456&token=token-value&oas_ver=2

Last updated: 4/4/2024, 8:56:52 PM