3rd party APIs

A powerful extension of the aiaibot platform is to call 3rd party APIs from within a Robot Workflow. This allows Robot to communicate with other machines opening a variety of use cases.

Register 3rd party APIs

In order to be able to call 3rd party APIs, one has to define (or register) them with the project. There are two ways to do that:

1. Use the Automation API. You can find a description of the endpoints for this API on our Developer page.

2. Use the APIs tab in the Robot module

    

APIs and endpoints

Endpoints are grouped together by the concept of an API. The API defines “global” settings that every endpoint inherits. Next to the hostname, it is possible to define request headers as well. Those headers apply to all endpoints of that API specification.

An endpoint consists of the following properties:

• Request method - we support the following methods:

  • GET

  • POST

  • PUT

  • PATCH

  • DELETE

• Request path

• Request header

• Request body

If an endpoint defines a request header with the same name as the API it belongs to, the header of the endpoint overwrites the header of the API.

Secret request header

A request header can contain sensitive information (API keys, authentication tokens, etc). Therefore, a request header can be made secret. The value of the header gets encrypted before it is stored in our database. Moreover, the value will never be transferred from the backend to the browser again. This includes the Workflow protocol as well.

Placeholder

In order to add dynamic content to a request, one can use placeholders. A placeholder starts with a dollar sign followed by an opening curly brace. Then comes an arbitrary name of the placeholder followed by a closing curly brace. Example: ${storyId}. This placeholder can be used in the following properties:

• Hostname

• Request header value

• Request path

• Request body

When calling an endpoint that has placeholders, one must map those placeholders to actual Workflow variables. The Call API Plugin shows a list of placeholders and a possibility to map them.

JSON in the request body

Nowadays a lot of modern APIs use JSON to exchange data. The body field of an endpoint can contain JSON, most likely including placeholders as well. As explained before, placeholders have to be mapped to actual Workflow variables so that at Workflow runtime, the body has the defined value.

When sending JSON as the payload of the request, make sure you include a content-type header with the value application/json. Robot checks the presence of this header. Only if Robot finds this header, the mechanisms below do apply.

Detection of variable types

Robot detects which type the mapped Workflow variables have. So if a variable of type text is being mapped to a placeholder, Robot automatically surrounds it with ". The same is true for variables of type collection. Robot automatically converts them to a JSON array by adding square brackets.

With a series of examples, the concept of placeholders in the body, especially when using JSON arrays, should be explained.

Example 1: Simple placeholder substitution

{
  "name": ${name},
  "age": ${age}
}

The placeholders ${name} and ${age} have to be mapped to Workflow variables in the Call API Plugin.
${name} gets mapped to a Workflow variable of type text with the value John.
${age} gets mapped to a Workflow variable of type integer with the value 20.

So the resulting JSON looks like this:

{
  "name": "John",
  "age": 20
}

Please note the following:

• The value "John" got automatically quoted, since the variable mapped to the ${name} placeholder is of type text.

Example 2: Array with simple types

{
  "name": ${name},
  "age": ${age},
  "hobbies": ${hobbies}
}

There is a new placeholder in the JSON body: ${hobbies}.
${hobbies} gets mapped to a Workflow variable of type collection. This variable contains the values Football and Reading.

So the resulting JSON looks like this:

{
  "name": "John",
  "age": 20,
  "hobbies": ["Football", "Reading"]
}

Please note the following:

• There is no need to add square brackets in the body of the endpoint. Robot detects that the variable that is mapped to the ${hobbies} placeholder is of type collection thus automatically creating a JSON array.

• The values in the array have “ . Robot detects the type of the entries in the collection variable. If the collection contains text, quotes are automatically added for each entry.

Example 3: Array with objects

{
  "name": ${name},
  "age": ${age},
  "hobbies": ${hobbies},
  "cars": [
    {
      "make": ${makes},
      "color": ${colors}
    }
  ]
}

When having an array that contains objects, you need to define exactly one prototype. This prototype will then be copied as many times as there are entries in the mapped collection variables.
${makes} gets mapped to a Workflow variable of type collection. This variable contains the values Tesla, Mercedes and BMW.
${colors} gets also mapped to a Workflow variable of type collection. This variable contains the values black and white. Please note, that this collection is one entry shorter than the collection mapped to the ${makes} placeholder.

So the resulting JSON looks like this:

{
  "name": "John",
  "age": 20,
  "hobbies": ["Football", "Reading"],
  "cars": [
    {
      "make": "Tesla",
      "color": "black"
    },
    {
      "make": "Mercedes",
      "color": "white"
    },
    {
      "make": "BMW",
      "color": null
    }
  ]
}

Please note the following:

• Entries from both collection variables are “mixed” together. This means, for the first object the first value of both collection variables is taken. For the second object, the second value of both collection variables is taken. And so on…

• The color of the last car is null since the collection variable mapped to the ${colors} placeholder had only two entries.