The API Widget

Tags

An API (Application Programming Interface) is a set of rules and protocols that enable different software applications to communicate and exchange data with each other. In other words, an API acts as an intermediary between two applications or services. It defines how these systems can interact and share information securely.

📌
Prerequisites To understand the content of this article, it is preferable to have some basic knowledge of APIs. We recommend that you first read the following article: Introduction to the Ermeo API

1. What is the API widget ?

The Api widget enables administrators to create API calls during a job in progress. This allows you to send and receive information, so that it can be displayed in your end-of-project reports.

2. Setting the API connection

2.1. Authorize user role

  1. Go to your user's role section. In the "Integration" section, activate the option: Show integration menu.

Once this option is ticked, a new section called "Integration" will appear in ermeo's main menu.

image
image

2.2. Create a new connection

  1. Click on the button: New connection
  2. Fill in the general information relating to the API to which you wish to connect (Name, Base URL).
  3. Select your authentication.

You will have 4 possible choices:

  • Without authentication (None): you can validate your connection directly.
image
  • Basic authentication: You will need to enter a user name and password in the second stage.
image
  • Header auth: You fill in one or more headers with their associated key and value.
image
  • Query Parameters: As with header auth, you will need to fill in your url parameters, with their associated key and value
image
  • Oauth2 : To finalise your authentication, you will need to fill in the following information: the Oauth 2 authentication url, the Oauth2 token url, your client id and secret, and your scope, as shown in the video below

For your information, the redirection url to be used by your api can be found at the bottom of the modal, in ‘Connection information’:

image
💡
Notes
  • The base url must end with a "/" at the end, if this is not the case, it will be added automatically.
  • If you have query params in the url, these will need to be entered in your path when you configure the query in the studio.
  • With an Oauth2 connection, your refresh token may expire after a period of inactivity for your connection, which varies depending on your API (check your documentation for details). If this happens, you will need to reconnect to continue using it:
image

2.2. Modify the connection

You can modify your connection if you wish by clicking on "Modify" on the chosen connection.

image

If you are modifying a Basic authentication connection, you only need to enter the password if you wish to change it.

image
💡
Notes
  • The authentication type cannot be changed.
  • Please note that any modification to a connection already in use with API bricks will have an impact on your forms.

2.3. Delete the connection

You can delete an API connection you have created.

If this connection is used in the configuration of your API bricks, you will see the number of bricks using this connection.

image
image

3. Set the API widget in the form

3.1. Set the API request

  1. Go to your form editing studio.
  2. Drag and drop the API brick from the "Workflows" section.
  3. In the brick settings, start configuring your request
image
  1. Select a connection configured on your "Integrations" page.
image
  1. Enter the chosen method: POST, GET, PUT, DELETE
  2. You can then complete the path of your url, and add any tags present in your form. If you have query params, you will need to enter them in your path.
  3. Choose the format of the query between JSON and XML
image
  1. You can include headers in your request, as well as a body. The value of a header and the body can contain tags.
image
  1. In step 4, choose the expected response format between JSON and XML
  2. Finally, you can test your query and save its creation:
  • If you have added tags to your query, and you wish to test it, you will need to enter a value for each tag by clicking on the "Enter tags" button.
  • You can also validate the creation of your query without testing it. However, we recommend that you test it to avoid any configuration errors.
image
image
  1. Finalise the settings for your API brick options:

You will be able to automate the click on your API brick, so that the person responding to the form doesn't have to click on the button that launches your API call, and you will also be able to hide this new brick from the user.

However, to be able to ‘Automate the click’, you will need to have poster conditions on your API brick.

image
💡
Notes
🛑
Limitations