Integration Question - API#
Integration question can be connected to an external resource using its API. We can then search for the results from the external service using the FAIR Wizard questionnaire interface. When we select an answer it is not only the text (such as a name of the database), but also a link to the external service to the selected item. The whole flow is denoted in the following diagram.
External Service Requirements#
If we want to connect an external service using the API there are certain requirements for it to make the connection to FAIR Wizard possible.
Allows search using free text
There must be a way to send a search phrase to the API so that it can filter the results based on it
Returns a JSON response with a list of results
The response must be JSON so FAIR Wizard can parse it
There needs to be a JSON list where all the items matching the search query are
It is possible to construct a link to the selected item
We also need to be able to construct the link to the item from the data we get in the response so we can provide it with the answer
Configuration#
The configuration is done in the knowledge model editor. First of all, we need to create a new integration and choose its Type to be API. Then, there are some metadata, such as ID, Name, or Logo URL.
Request Configuration#
In the Request section, we configure how to make an HTTP requests to the external service’s API. For that, we need to configure the following (the specific values depends on how the API works):
Request URL - what is the URL where we want to send search requests
Request HTTP Method - what HTTP method should be used
Request HTTP Headers - some headers might be needed, such as
Accept: application/json
to have a correct response typeRequest HTTP Body - if we need to send some HTTP body
Allow Empty Search - some APIs don’t work if we try to search with an empty string, turn this of it’s the case
There is a special property ${q}
that we can use within those fields. The property represents the string that users type to the questionnaire. So for example, we can write Request URL as:
http://example.com/api/search?q=${q}
Response Configuration#
In the Response section, we configure how to process the JSON response from the external service. For that, we need to configure the following:
Response List Field - where in the JSON response is the list of items corresponding to the search query
Response Item ID - what field represents an item ID in the returned JSON
Response Item Template - how we want to present the result to the user
We can use Jinja2 templates (Ginger implementation) in Response Item ID and especially in Response Item Template to make the response item look better.
Secrets and Other Properties#
Sometimes, we might need to use some secrets (for example for authentication token), additional properties (such as API URL if we want to use different one for testing and production), or basically any information that we do not want to include in the knowledge model. In that case, we can define some properties in the FAIR Wizard settings.
We need to navigate to Administration → Settings → Knowledge Models and there is a field called Integration Config. It is a YAML organized by the Integration ID at the top level and key value pairs for each property.
We can fill some properties in. So, for example, if the INtegration ID of our integration is ourIntegration we can write:
ourIntegration:
authorizationToken: "abcd"
apiUrl: "http://example.com/api"
Then, in the configuration of our integration, we can use these properties in the request configuration, so for example the Request URL can be:
${apiUrl}/search?q=${q}
And we can add a header such as:
Authorization: Bearer ${authorizationToken}
Note
These properties can be accessed only from the integration with matching ID.
Video Tutorial#
We have the following video tutorial showing how to set up the integration question using API.