API connectors

API connectors, short for Application Programming Interface connectors, are used to connect to external APIs and exchange data. They are data sources that can be used in any component of the form that requires a data source. They can be used to populate fields with data from external sources, or to send data to external sources.

It is important to note that API connectors are defined globally at the project level and are shared across all forms within the project. This enables you to reuse the same API connector in multiple forms. In the API Connectors section we can find all the APIs defined for the current project.

To use API connectors in forms, they must be added to the form. This makes the API connector available for use in the form and any of its components that require a data source, most commonly select/coded text fields, column lists, and widgets.

Creating a new API

To add a new API connector, click the Create new API button. A new API window will open:

Here you can add some common settings, then you can add several endpoint calls to the API connector.

API connector common settings

An API Connector can have multiple API calls, and all API calls share common API connector settings:

• API name
• Base URL
• Authentication settings
• shared headers
• shared parameters
• pre-request

API name: API name is the name by which all requests in the API connector are accessible. For example, the API name can be Demography.

Base URL: All API calls will be prefixed with this URL so that it does not need to be repeated for each call made. In the base URL you can also use variables and functions with expression assistant.

Authentication: Most APIs require authentication. The most common authentication for the APIs are:

• Basic authentication that requires username and password,
• EHR Platform credentials means that authentication is inherited from EHR Server credentials, and
• Bearer authentication (OAUTH2) that requires a token.

TIP: Bearer or username and password can be set as variables and then added to authentication. This way, the configuration is managed with variables alone.

Shared headers are headers applied to all API calls. For example, if all the calls need an encrypted header, you can add it here. You don't need to add the same header to each API call.

NOTE: When you have a specific type of authentication, you can add it to the shared header.

Shared parameters are parameters used in all API calls within the API connector. For example, patientID could be a parameter you might need to use in all the API calls.

Pre-request is a script that is executed before each API call. It can be used to set up the environment for the API call. For example, calling an additional API to get an authentication token and setting it to the headers of the API call. Read more about pre-request and post-response scripts or see an example of how to use pre-request to retrieve authentication tokens.

Create a New API Call

To add a new API call, click the Create new API call then:

1. name the API call, e.g., Get All Users,
2. select the API method: POST for create, GET for read, PUT for update/replace, PATCH for update/modify, or DELETE for delete,
3. enter the API Model / Endpoint,

NOTE: API endpoint can also be a variable you set in the Variables menu. For example, terminologyURL is a predefined API address you can configure in the Variables menu. You can also add URL addresses for other APIs.

4. add headers (optional),
5. add parameters (optional), and
6. click the Start test call button
7. Save the API call using the Save button

The API can be used in the form after the Start test call button was clicked to initialise the api

In the video, you can see how to add a list of users from the sample jsonplaceholder API.

For more information about using APIs in forms, see API connectors in the Bottom Panel section.

NOTE: When sending POST, PUT, and PATCH methods, you also need to provide a Body type and Body data to send to an API endpoint. Read the API and variables examples for a practical example.

Importing APIs from OpenAPI definitions

You can import your OpenAPI 3.0 and 3.1 definitions and create APIs from those definitions. Importing supports both YAML and JSON formats.

To import an API definition, click the Import OpenAPI button. You can choose to upload a file, enter a URL, enter a cURL or paste your raw JSON or YAML.

• File: Upload a file from your local machine.
• URL: Enter the URL of the OpenAPI definition.
• cURL: Enter the cURL command to fetch the OpenAPI definition when the the call requires authentication with a username and password.
  • cURL command example: curl -u username:password https://sampleOpenApi/openapidefinition
• Raw JSON/YAML: Paste the raw JSON or YAML content of the OpenAPI definition.

Import OpenApi dialog

After successfully importing your API, you can edit some of the configurations of the API, like base URL, or use it in forms.

APIs that were imported from OpenAPI definitions will have the tag "OpenAPI" in the title to indicate that they were imported from an OpenAPI definition.

Open API connector with the tag "OpenApi" in the title

OpenAPI definitions that require Authentication

If your API definition requires basic authentication, the import dialog will warn you that the call retrieval was not successful and requires authentication. you have two options to authenticate:

• use cURL command to fetch the OpenAPI definition when the call requires authentication with a username and password
  • example: curl -u username:password https://sampleOpenApi/openapidefinition
• open a new browser tab and paste the URL in the address bar, then enter the username and password when prompted. After that copy the response displayed and paste it in the import dialog

  

  Open API definition that requires authentication

Updating OpenApis

When you import an OpenAPI definition, the system creates an API with the calls and parameters defined in the OpenAPI. You cannot add or remove API calls from the imported API, however, you can edit the sample values in headers and parameters in those calls.

If the OpenAPI definition source was changed, you will need to re-import the definition again. When you re-import an OpenAPI definition, the system will update the existing API instead of creating a new one. If any calls were deleted from the OpenAPI definition, they will be deleted them from the API. If any new calls were added to the OpenAPI definition, they will be added them to the API. The same goes for any parameters; the import process adds or removes any parameters that were added or removed from the OpenAPI definition.

Making changes to the OpenApi connector

You cannot add or remove API calls from the imported API, however, you can edit the sample values in headers and parameters in those calls.

If you need to make changes to the API calls, you can always duplicate the API and make the changes in the duplicated API. To duplicate an API, navigate to "Administration" and click on the "API Connectors" section. Find the API you want to duplicate and click on the three dots on the right side of the API name. Select "Duplicate" from the dropdown menu. You can now make changes to the duplicated API without affecting the original API.