Skip to main content

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.

Api connectors overview

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:

Import button image

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, and
  • shared parameters.

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.

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.

  1. add headers (optional),
  2. add parameters (optional), and
  3. click the Start test call button
  4. Save the API call using the Save button
warning
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.