API Endpoint Management

In the API Platform, an endpoint exposes the functionality and output data of a callable recipe. Similar endpoints are grouped into an API collection, where other users and apps can consume the endpoints.
Each API collection page displays the API endpoints in that collection. Navigate to Tools > API platform > API collections and select an API collection to see the endpoints.

API collection overview

Typically several endpoints are uploaded together as part of the process of creating an API collection. Once you create an API collection, you can add more endpoints to the collection.

The sections below guide you through configuring a new endpoint.

Configure a new API Endpoint

Before you start

• Create a callable recipe
• Create an API collection
• We recommend that you organize callable recipes with endpoints belonging to the same API collection within the same folder in your Workspace. For example, a set of Salesforce endpoints that are intended to be called by recipes used by the sales team might be put together in an API collection. This is not required. Learn more about API endpoint URLs.
  

Do these steps to configure an API endpoint:

1. Create a new endpoint
2. Test the endpoint
3. Activate the API endpoint

Create an Endpoint

Before you start

• Review the endpoint path guidelines

1. Select the API collection in which to create the new endpoint.
2. Click Create new endpoint.
   The Add new endpoint window appears. Add new endpoint window
3. Fill in the following fields:
   • Name: Enter a descriptive name for the endpoint.
   • Callable recipe: Select the callable recipe from the drop-down list. The list contains all the callable recipes that you can access.
   • Method: Select the HTTP method.
   • Path: Enter the endpoint path, which can include path parameters.

   Ensure the endpoint path conforms to these guidelines.

4. Click Add endpoint.
   The new endpoint appears in the API collection page.
   You can make changes to your API endpoint by selecting the ellipsis (•••) in the upper-right corner of the endpoint.
   

Next test the endpoint.

Path templating

This feature is only available for collections with prefix enabled.

Path parameters allow you to specify resource identifiers in the URL path. When an API request is made, the values input in path parameters are passed to the associated datapills in the callable recipe. We recommend that you first configure the datapills in the Callable recipe trigger, then configure the endpoint path parameters.

Use curly braces {} to mark parts of the URL as a path parameter. Refer to the screenshot below for an example.

URL path templating

Endpoint path guidelines

• An endpoint path can contain one or more segments separated by a /
  For example, users/{user_id}
• Each segment can contain either a static path (users) or a parameter ({user_id}), but not both (user-{id})
• Path parameter names support alphanumeric or _ characters to comply with datapill names
• An endpoint path cannot contain multiple parameters of the same name
• Each endpoint must be a unique combination of method and path
  • An endpoint of /user/{id} is not allowed if /user/{ID} already exists in the same collection, unless they have different methods
  • An endpoint of /user/{id} is not allowed if /user/{user_id} already exists in the same collection, unless they have different methods
• Path matching is done from left to right and static segments are given priority over parameterized segments

WARNING

• If you update the endpoints once they are being used by recipes or API clients, you may also have to update the recipes or scripts to prevent errors.

Return to Create a new endpoint

Example

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 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"}'

Return to Create a new endpoint

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

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

1. From the API collection page, open the new endpoint.
2. Click Try it out to make a test call to the endpoint.
   The button is located to the right of the Parameters section.
3. Enter the input parameters in the Parameters section of the endpoint description.
   Often, the Example value shown in the endpoint description will suffice for a test. For example:

Parameters input

4. Click Test. See the following screenshot for an example of a success 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 contained values that are invalid for the target recipe.

If you are configuring an endpoint, proceed to the next section to activate the endpoint.

Activating or Deactivating an Endpoint

Control which endpoints are callable from the API collection page using the Active/Inactive toggle beside each endpoint. When an endpoint is created as part of a new API collection or added to an existing collection, the endpoint is set to the Inactive state. API collection overview page

You must activate the endpoint to allow other recipes to call it.

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; the API gateway rejects API calls to an inactive endpoint. However, the associated recipe continues to run.

WARNING

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