Workato docs Return to Workato
Edit this page
GitHub (opens new window)
  • Introduction
  • Getting started
  • Product Updates (opens new window)
  • Concepts
  • Connecting apps
  • Building recipes

  • Running recipes

  • Troubleshooting

  • Data types and formulas

  • Tools
  • Files and attachments

  • Batch processing

  • Teams and collaboration
  • People Task by Workato
  • Recipe lifecycle management
  • On-prem connectivity
  • Key features
  • Workbot for Slack
  • Workbot for MS Teams
  • Workbot for Workplace
  • API Platform
  • Connectors

  • Universal connectors
  • Community connectors
  • Connector SDK
  • Custom OAuth profiles
  • Workato API
  • Security
  • Training & Certification
  • Contact us

# API Endpoint Management

Workato groups several similar API endpoints into API collection. The API collection overview page displays all API endpoints in this collection. Navigate to this page from Tools > API Platform > API collections tab > Select an API collection.

API collection overview API collection overview

# Setting up an API Endpoint

In this guide, we will go through API endpoint configurations

  • Create and update an endpoint
  • Setup path parameters
  • Activate an API endpoint
  • View individual endpoints
  • Test individual endpoints

# Pre-requisites

The first step in setting up an API endpoint is to create a recipe that uses the Callable recipes by Workato connector as a trigger.

The next step is to organize these recipes into one or more API Collections. Generally, an API Collection should contain endpoints whose access pattern has some common features, so that you can manage them together. For example, a set of Salesforce endpoints that are intended to be called by recipes used with the Sales team might be put together in an API Collection.

# Creating an Endpoint

Clicking on Create new endpoint within the API Collection tab brings up a dialog that allows you to add a new Endpoint to the API Collection. The recipe for this endpoint can be chosen from any callable recipe - it does not have to be in the same folder as other existing collection endpoints. Learn more about API endpoint URLs here.

Create endpoint dialog Create endpoint dialog

Endpoint configuration fields Description
Name Give this API endpoint a descriptive name.
Callable recipe The callable recipe to be called by this API endpoint.
Method The HTTP method.
Path This path is added to the API prefix and collection path. All endpoint paths are subjected to these contraints.

Click Add endpoint to finish creating your API endpoint. You can make changes to your API endpoint anytime by selecting the ellipsis (•••) icon in the upper-right corner of the listed endpoint.

# Endpoint path rules

  • Endpoint path can contain one or more segments separated by /
  • Each segment can contain either a static path (users) or a parameter ({user_id}), but not both (user-{id})
  • All endpoints must have a unique combination of method and path
  • Two or more path parameters in the same segment sequence are considered duplicates
    • GET /users/{user_id} is indistinguishable from GET /users/{id} - only one is allowed
  • Path matching is done from left to right and static segments are given priority over parameterised segments
  • Path parameter names can only contain alphanumeric or _ characters to comply with datapill names
  • An endpoint path cannot contain 2 parameters with the same name

WARNING

Changes may require clients of the API to make adjustments on their end, so that their recipes, scripts, etc. still work.

Deleting an endpoint removes it from the collection and makes it inaccessible to any clients that had previously been granted access to it through the collection.

# Path templating

Path parameters allow you to specify resource identifiers in the URL path. Use curly braces {} to mark parts of the URL as a path parameter. This is only allowed for collections that has prefix enabled.

URL path templating URL path templating

Callable recipes can be configured to accept inputs from the API caller. These inputs are converted into datapills in the recipe. See Callable recipe trigger.

If the API endpoint requires a salesforce_id, you can use a path parameter to provide the salesforce id (5003000000D8cuI).

curl -X PUT 'https://apim.workato.com/api-collection/users/5003000000D8cuI' \
    -d '{"Email": "Matt.Jones@example.com","displayName": "Matt Jones","BillingCity": "San Francisco"}'

The trigger output in the recipe will look like this:

{
    "request": {
        "salesforce_id" : "5003000000D8cuI",
        "Email": "Matt.Jones@example.com",
        "displayName": "Matt Jones",
        "BillingCity": "San Francisco"
    },
    "Context": {+}
}

Overlapping keys

If the same namespace is present in the path parameter, query parameter and/or request body, Workato will prioritize the value given in the path parameter.

In this example, the datapill salesforce_id will take the value in the path parameter (5003000000D8cuI).

curl -X PUT 'https://apim.workato.com/api-collection/users/5003000000D8cuI' \
     -d '{"salesforce_id" : "068D00000000pgOIAQ","Email": "Matt.Jones@example.com","displayName": "Matt Jones","BillingCity": "San Francisco"}'

# Activating or Deactivating an Endpoint

Toggle individual endpoints between Active/Inactive. See here for more information.

State Description
Active Active endpoints are callable from API requests. To set an endpoint to the Active state, the recipe associated with the endpoint must first be running.
Inactive Inactive endpoints cannot be called remotely. Using this slider to toggle to Inactive does not, however, stop the associated recipe.

# Viewing an Endpoint

Select an API endpoint from the API collections overview page to bring up a page with detailed documentation on that endpoint. These details are also available in this OpenAPI file downloadable from the API collections page.

There are several sections within the information section.

Endpoint information section Endpoint information section

# Implementation notes

These come from the recipe description and describe what the recipe does.

# Parameters

This section lists the parameters that are required to be input as part of the call to the API. For a GET method, parameters should be sent as query strings that are part of the URL. For a POST or PUT method, parameters should be sent in JSON format in the body of the request.

# Response

When a call to the endpoint is made, a status message will be returned to the client. This section also documents the responses if the call to the endpoints was successful and any response data that is sent along with the status.

Code Description
200 If the call was successful, the response message will be returned with a "success reply".
error codes If a call to the API fails, then an error status will be returned to the HTTP client. This section documents the possible error codes that might be returned.

# Testing an Endpoint

To the right of the Parameters section, there is a Try it out button. This can be used to make a REST call to the endpoint for testing purposes.

The input parameters can be entered in the Parameters section of the endpoint description. Often, the Example value shown in the endpoint description will suffice for a test. For example:

Parameter input Parameters input

Once the required parameters are entered, click the Test button at the bottom of the screen. A successful test might produce results like this:

Test response Test response

This shows a "Success" return code (200).

If the response value is not 200, the test results in an error. There can be numerous reasons for an error.

The most common error when performing a test from the same account that owns the callable recipe is "Invalid request" (500). This usually indicates that the input parameters were incorrect: not all required parameters were supplied or had values that are invalid for the target recipe.

# More information

Read our walkthrough for API collections configuration:

  • How to create an API collection
  • How to edit an API collection
  • How to customize URL path for API collection
  • How to obtain machine-readable documentation (openAPI)

← API Collections API Access Policies →

Didn’t find what you are looking for?
Search our resource library View getting started guides, tutorials, training videos, webinars and FAQ Ask our community View questions and answers from other users and Workato experts. File a support ticket File a support ticket for critical issues that require a higher level of support.
Privacy Terms (844) 469-6752 Workato 2021