API Collections Management

The API collections page displays all API collections under this account (individual or team account). Each API collection is comprised of 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.

Navigate to Tools > API platform > API collections.

API Collections Tab

Configure an API collection

Before you start

• Create an API recipe
• Organize the API recipes into one folder. We recommend that you organize API recipes with endpoints belonging to the same API Collection within the same folder. An API Collection can be associated with a folder so that any new API recipes added to the folder will be included in the collection automatically.
  

Create a new collection

1. Click Add new API Collection.
   The Create API collection window appears: Window to select API source
   

2. Enter the Collection name, Version, and Description.

3. In the Recipe folder drop-down list, select the folder that contains the API recipes.

4. Click Next.
   The Review endpoints window appears, containing the list of API recipes that are imported to the API collection as endpoints. You can edit the endpoint names, URLs, and methods, as well as add or delete endpoints later. Window to review endpoints

5. Click Create API collection.
   You are returned to the API Collections list, where you will see the new collection listed.
   Next, activate the endpoints. By default, all new endpoints are inactive; you must activate an endpoint to allow other recipes or apps to call it. To learn more, see Activating or deactivating an Endpoint

6. Click the new API collection to open the collection overview page. API collection overview page

7. Click the toggle on the right of an endpoint to activate it.
   Next, configure the Collection, URL, and Sharing settings.

8. Optional: Click the Settings tab to configure the following settings:

   • Optional: Change the version number.
     Note: API Collections are versioned using a unique 1-10 character version identifier. Collections with the same name but different versions are distinct objects.
   • Optional: Enter a description about the API collection.

   API settings tab

9. Optional: Click the URL settings tab to customize the collection path. For example, you can use this field to differentiate collections for sales, marketing, or HR.

WARNING

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

The screenshot below highlights the section of the URL that can be customized in this tab. The domain and path prefix are customized from the API platform Settings tab. URL settings tab

10. Optional: Click the Sharing tab, where you can add the collection to the workspace API library. By default, new collections are hidden from the library. If you click Show in API library, anyone in your workspace can find the collection and request access to it. Share API collection with the library

Next, enable specific users or apps to access this collection by assigning this collection to the clients' access profile. Proceed to create a new access profile.

Edit an API Collection

Once you have created an API collection, click the API collection open up the collection overview page. From this page, you can add, remove, or edit endpoints that are available within this collection.

API collection overview page Related topics:

• Create new endpoint
• Test an endpoint

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. This 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 like Postman. This format is called OpenAPI, also known as Swagger. Currently, Workato supports version 2.0 (opens new window) of the specification.

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