API Endpoint

Overview

API Endpoints act as the gateways through which external applications interact with your automation, allowing real-time data exchange. 

These endpoints are URLs pointing to specific operations or data within your system, making them accessible for automated processes or integrations.

Note

Before creation of API endpoint, ensure you have one or more API automations that have been deployed.

Create your first API Endpoint

After you have created the API collection, you can create your first API Endpoint by clicking on “New Endpoint” in the top right corner.

Follow the prompts to create your API Endpoint. This may involve entering the following fields:

1. Endpoint Name: Provide a name to your API endpoint

2. Description: Enter a concise explanation of what the endpoint does.

3. Resource Type: It refers to whether you want to call a callable or webhook-based automation from this API endpoint

   • Callable:. Only automations with a "Trigger from an API endpoint" as trigger will appear in the API Automation selection.

   • Webhook: Only automations with a "Trigger from webhook"  as trigger will appear in the API Automation selection.

4. API Automation: Depending on the resource type chosen, select an appropriate API automation from the available options.
   Each automation turns into its endpoint, which gets executed whenever the endpoint is called.

5. Versions: It represents the current stage of your API, reflecting any new features, modifications, or bug fixes introduced since the last version.

6. Endpoint Path: Specify the path for the endpoint URL, this can also include the path parameters.

7. HTTP Method: Select the HTTP method (GET, POST, etc.) to be used for the API endpoint.

   • GET Method: If you choose GET, you have the option to cache the response. You can enable caching by checking the "Cache Response" box and setting up the cache duration and key (which could be query parameters, path parameters, or headers). 

   • POST Method & Others: If you need to send data in the request, select an appropriate method other than GET. 

8. Customize Timeout: You can also specify the maximum time for the automation to wait before considering the request failed.

   
   
   

   Note

   GET requests cannot contain a body; if your automation requires sending data, use POST instead.

API Endpoint Attributes

Once you have created an endpoint, you can see the following attributes of the endpoint: 

• Automation Name: This is the title of the automation process that gets activated when the specified API endpoint is accessed. Clicking on the "See Automation" link will take you to a preview page for this automation.

• URL: This is the address (endpoint) of the API that can be reached out to from outside sources.

• Endpoint Type: Indicates the HTTP request method (e.g., GET, POST) used by the API endpoint.

• Response:

  • Code: The status code that is sent back after the API has been successfully processed.

  • Media Type: Specifies the format of the data that will be returned.

  • Schema: Describes the structure of the output data.

• Parameters: Lists of query or path parameters that are part of the automation's configuration.

  
  

Fallback Response

It serves as a default reply when the API cannot fulfil a request due to issues like server errors, invalid input, or when no other specific response is applicable.

Configure Fallback Response

• HTTP status code: you can define the status code that will be sent along with the response, such as 500 - internal server error, etc.

• Headers: headers are defined in key-value pairs. You can configure multiple headers for the response.

  
  

• Response body: define the response body in JSON format. You can also define the response body in different locales by clicking “Add Another Response”.

• Finally, Click on the “Create button” to create the fallback response

Activation and Access Control

Newly created endpoints within a collection are inactive by default. Activation is necessary for these endpoints to be callable. For activating the endpoint, the toggle associated with the endpoint needs to be turned on. 

Additionally, manage who can access these collections by assigning them to a client's access profile, ensuring controlled and secure API access.

Refer

You can read more about API Clients here.

Best Practices

1. Naming Conventions: Use clear, descriptive names for your endpoints. (e.g., /fetchUsers for a user resource).

2. Version Your APIs: Include version numbers in your endpoint paths (e.g., /api/v1/users).

3. Performance Optimization: Use caching judiciously for GET requests to improve response times.