# 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
# 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
| 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 fromGET /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
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
# 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:
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
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: