API node
The API node lets you add a new API from a third-party system and access it in conversational flows.
There are three ways by which you can add an API to the API node:
Import API
If you have a CURL script or a JSON file you can import that to yellow.ai.
Import cURL
Click Import API.
In Name enter a name for your API, in Type choose the API type as cURL and in cURL field, copy/paste the cURL snippet.
Click Import.
Import JSON file with API details
Click Import API.
In Name enter a name for your API, in Type choose the API type as JSON and in the Import field, click Drag & Drop to upload the JSON file or drag and drop the file directly.
Click Import. The API details such as Headers, Params, Dynamic variables(that collects dynamic data) gets auto populated in the API node.
Create new API
This option lets you add a new API on the go:
Click Create new API.
Fill in the following fields:
Fields | Descriptions |
---|---|
Name | Enter a name for your API |
Method | Choose the method of your API request. |
URL | Paste the API URL. |
Description | Describe the functionality of your API. |
Headers | Headers in API requests are additional pieces of information sent alongside the main request. For example, if you are authenticating an API, set the Key as Authorization and the Value as the API key. |
Params | API parameters are essential components used when making requests to an API. They serve as specific instructions or information that you include with your request, helping the API understand and fulfill your requirements accurately. Examples of key-value pairs for static and dynamic parameters: Static parameter: - Key: botId - Value: x766543323dwe_34 Dynamic parameter: - Key: city - Value: {{{city}}} In these examples: The botId key has a static value (it remains constant). The "city" key has a dynamic value represented as {{{city}}}, indicating that the value will be dynamically replaced with the actual value of the "city" parameter during runtime. |
Body type | The body in an API is the main content of the request containing data or information that should be sent to the third-party server. For POST, PUT, or DELETE methods, you can add the request body under the Body section. The supported formats are x-www-form-urlencoded, JSON, XML, GRAPHQL, form-data, and raw. Multipart/form-data is not supported. |
Dynamic variable configuration | Here's where you will assign a variable to collect the dynamic value from users. The data type of the variable and dynamic value should be the same. |
Additional configuration to enhance the API usage
The +More button holds configurations that would optimize the usage of that particular API.
Configuration | Description |
---|---|
Timeout | Maximum time allowed for API response. |
Retry on failure (5xx) | Number of attempts to retry in case of server. errors |
Follow redirect(s) | Determines if API should automatically follow. redirects |
Encoding | Method used to encode data (for example JSON, XML) |
Use strictSSL | Enforces strict SSL certificate validation. You might not get response if this is enabled and there is some problem with SSL certificate. |
API alerts on | Events triggering alerts (for example errors, high traffic). |
Default message on invoking API | Default response or action when API is invoked |
API failure message (4/5xx code) | Message displayed upon API failure with specific codes. |
Add MTLS auth | Enables mutual TLS authentication for enhanced security. |
Configure environment keys | Adding environment variables allows you to store and manage dynamic values such as API keys, tokens, or any sensitive information that keep changing for each environment. This makes it easier to manage and use APIs seamlessly across your testing and development flows. |
Use existing API
If you have already added the API to the bot either through API node or through the API section, you can fetch the API here.
Click Use existing API.
In API, choose the API. All the details of that API will get auto-populated in the respective fields
Test the API
After adding an API, you can test it to ensure that the API is working properly.
Click the API node and click Test response.
Provide a sample input for your dynamic variables (if any) and click Run. If the API works successfully, you will receive a response code of 200.
Store the API response
You can store API responses in a variable and filter out the required information and display it to the consumer. To do so:
API responses typically belong to one of three data types: object, array, or string. It's important to store the received response in a variable with the same data type as the response.
Click the API node and click Test response.
Scroll down and go to Store all response. Create or choose a variable in which you want to store the API response based on its datatype.
Display API response
Depending on the response datatype, use a syntax to fetch or display the necessary data from the API response.
To display the received API response:
Add a message node to the API node.
Choose the variable created in the previous section(step 2).
Along with the variable, use a syntax to filter out the required data from the API response. You can refer to the following table for syntaxes to use depending on the data type.
Datatype | Syntax |
---|---|
Array | {{{variables.variablename.[position of the array].fieldname}}} |
JSON Response Array | {{{variables.variablename.arrayname.[position of the array].field}}} or {{{variables.variablename.fieldname}}} |
String | {{{variables.variablename}}} |
You can tweak the above syntaxes based on the API responses you recieve.