The API Connector box is a box available in all Alcmeon scenarios. The goal of this box is to do 2 main actions:

an API call to an external service
extract some information from the answer and save them in scenario variables

Configuring this box is quite easy. You need to specify which HTTP method you want to use (only GET and POST are supported so far) and the URL of your API endpoint.

If your API service requires an authorization token you can use one of the oAuth2 authorizations created (see chapter below) by selecting it in the External Authorization dropdown of the box.

If you selected a GET, no other info will be required for performing the API call.

If you selected a POST you can also add a body to your request. NB The body must be in JSON format, elsewhere the call will fail.

NB We automatically add 2 headers to this call:

x-request-id: a unique identifier generated with UUID4
x-client-id: the string 'alcmeon' (useful to identify the caller)

How to use scenario variables in API Connector

You can use scenario variables previously set in this box. This will allow you to parameterize your request depending on user data you need.

Example: You want to get information about the order of the user your are interacting with. Your API has a GET method with url: http://my-api//<order_id> .

You need is to the order id of the user so that you can perform the call

First, collect the order id of the user (by asking it to him for instance)
Then save this value to a scenario variable order_id
In your API Connector box, parameterize the url with the following syntax

https://my-api/{{order_id}}

You can use these variables in your API endpoint url or in the body of the POST request.

Bonus: in case you want to use the external id of the user, we provide a pre-filled variable: {{user_id}} to be used in the same way as above.

Handle API answers

In the API Response section of the box you can configure which data you want to extract from the response to use later in the scenario:

You will need to define the JSON path of the field you want to extract and choose the name of the variable to assign it to. If you are not familiar with the JSON paths parsing you can read the doc https://www.ionos.com/digitalguide/websites/web-development/python-jsonpath/

How to debug errors occurred during API Connector box calls

As the API Connector box performs HTTP calls we implemented a mechanism to retrieve errors occurred during these calls (e.g. HTTP status code different from 200, json path not found in result, ...) .

We provide 2 methods to get them:

receive them by email
export the list of last 50 errors from the box

1
To be able to receive errors you must add your address email to "Outgoing email" page. The first line in the box contains a link to this page:

You will be notified for each FIRST daily error the box will trigger (only the first to avoid to spam you).

To export the list of last 50 errors you can simply click on the correspondent option in the box.

oAuth2 external authorizations

We allow clients to configure oAuth2 authorizations (with tokens associated) which can be used to perform API calls to an external server (for example in the API Connector box).

So far only 'Client credential' grant type is possible (see https://oauth.net/2/grant-types/)

Create a new oAuth2 authorization

From the Settings menu, open the page "External authorizations". This page will list all the created authorizations allowing to edit and delete them or create a new one.

To create a new one, click on the New Authorization button: a new page will appear where you can configure your data:

The fields in this page are required to perform the API call (POST) to the selected endpoint, which will allow to get a valid token to be used later.

Name: the name you want to assign to your authorization. It will be used when retrieving the list of the authorization in the API Connector box . NB Name must be unique, you can not have 2 authorizations with the same name.
Client id : the client id associated to your oAuth2 authorization service
Client secret : the secret associated to your oAuth2 authorization service . NB For security reason, client secret will be hidden when showing authorization page. You can edit it but it will never appear (except at the creation step)
Endpoint : the endpoint which will be called to get the token associated with the authorization.
Scope : your external service can support different scopes for the client credentials grant
A list of headers with format key/value.

When clicking on Save we will take care of performing the API call to get the token.

NB We automatically add 2 headers to this call:

x-request-id: a unique identifier generated with UUID4
x-client-id: the string 'alcmeon' (useful to identify the caller)

If everything went well, you will be redirected to the authorizations list page where you will see the item just created and your token will be available to be used when necessary. If something went wrong the error will be prompted in the GUI and you will be able to modify your fields data.

An example of returned value for the above API call could be:

{
  "access_token": <your access token>,
  "expires_in": <the token validity delay in seconds>
}

For this type of oAuth2 authorization (i.e. client credentials) when a token is expired we'll take care of requesting a new one.