Injecting Data – Connect to an API

Connect to an API (Datasource):

An application programming interface (API ) allows the user to access predefined and existing information that is stored on a server. Rainbird can use an API to access external information and then to use the external information to create concept instances and facts at run-time. 

Using an API to access external information saves time when working with vast quantities of data that may already exist somewhere, or when working with live data which is prone to change, as the data does not need to be hard-coded inside of a knowledge map.

This article will demonstrate how to build a knowledge map that uses an API to retrieve the make and model of a vehicle from a database after the user provides Rainbird with a licence plate number. 

1. Create 5 string concepts

  • Person‘ – the user
  • Vehicle‘ – the licence plate number
  • Model‘ & ‘Make’ – the information we will request from the DVLA
  • ‘Result’ – which will be retrived from the data source

2. Create relationships to link the concepts, as shown in Figure 1:

Figure 1: Map framework

3. Now it’s time to create the main rule of the knowledge map.

Open the ‘gets‘ relationship and click ‘Add rule’. Click ‘Add Condition’ and add the following conditions to the rule (see Figure 2 for the complete rule):

%S[UBJECT] ‘owns’ %VEHICLE &

%VEHICLE ‘has make’ %MAKE &

%VEHICLE ‘has model’ %MODEL

The rule tells Rainbird to show the user (%PERSON – the subject of the query) a result (%RESULT – the object of the query) if all three conditions are met.

4. As we want Rainbird to return both the %MAKE and %MODEL as the result (or the object) of the query, we will need to create a string concatenation.

Returning to the rule, click ‘Add Expression’ and input the following into the expression box:

‘This vehicle is a ‘ + %MAKE + ‘ ‘ + %MODEL

In the assign expression to variable box, assign the string concatenation to %O . Now Rainbird knows to output the string concatenation as the object (or result) of the query. Figure 2 below details how the rule should be structured:

Figure 2: Rule on ‘gets’ relationship

Before hooking up the map to the datasource, it is worth testing the map’s logic by creating some concept instances and running the ‘gets’ query to ensure Rainbird returns the expected results and the logic is working correctly

With the framework and rule built, the knowledge map can now be connected to the datasource.

5. It’s time to set up the datasource that Rainbird will call to to fetch the pieces of data required by the model.
Right click the blank space of the knowledge map, and click ‘Add Datasource’. In the pop-out window, name the datasource. Next, tie the datasource to the ‘Vehicle’ concept, by selecting  ‘Vehicle’ from the Subject (%S) dropdown list underneath the datasource name, as shown in Figure 3 below:
Figure 3: Creating a datasource and assigning it to a concept
The datasource is tied to the vehicle concept, as we want Rainbird to call to the API to create facts on the ‘has model’ and ‘has make’ relationships with the vehicle licence plate number that will be entered at run-time being the subject of the facts. 

6. Staying on the ‘Add Datasource’ menu, add the following URL to the API Request box:

Figure 4: API request

The URL comprises:

  • The hostname:
  • The path: api/datapackage/VehicleAndMotHistory
  • Different parameters:
    • v : 2
    • api_nullitems : 1
    • auth_apikey : YOUR_API_KEY

You will need to replace YOUR_API_KEY with your API authorisation key. As we want Rainbird to access the dataset pertaining to the licence plate number entered at runtime, replace VEHICLE_NUMBER with {{%S}}. {{%S}} indicates to Rainbird to replace the value with a concept instance of the subject the datasource is tied to.

7. Leave the Headers blank. Different headers are sometimes needed to parse information through the API (if you’re unsure, refer to the API documentation you’re using). Here is an example of a populated header:

Figure 5: Headers example

8. The current API call will return the following information

Figure 6: Raw data from the API call

The raw data can be viewed  in a browser by taking the API URL and replacing the {{%S}} with a valid licence plate number and YOUR_API_KEY with an api key. As we want to find the data path for the make and model, we can copy the raw data into a JSON beautifier to more easily identify the correct JSON path:

Figure 7: Identifying the data paths

9. Once the path has been identified, return to the datasource menu, navigate to the Output Facts section, select the relationship you want to inject the data on (in the case of the example model, ‘has make’ and ‘has model’, and put in the JSON path you just identified:

Figure 8: Creating output facts

Now, the query can be run.

Rainbird can use results of relationships generated at runtime as variables in API calls.

Let’s modify the model that was previously built in this article to allow the user to choose whether he wants to retrieve the make OR model of a vehicle.

1. Returning to the example model,  create a new concept,

  • ‘Choice’
  • ‘Final Result’

2. Link the new concepts with new relationships, as shown in Figure 8:

Figure 8: Creating additional relationships

3. Open up the datasource that was previously created, and add the following to ‘Input Variables’ (see Figure 9):

%PERSON owns %S

%PERSON has choice %CHOICE

4. Next, navigate to ‘Output Facts‘ in the datasource menu, and add a new relationship, ‘has final result’ to the list. In the datapath, replace the make or model with %CHOICE, as shown in figure 9 below:

Figure 9: Adding Input Variables and amending the Output Facts

Now, the query is ready to be run. When querying the “has final result” relationship, Rainbird will ask the user whether they want to look up the make or model. Depending on the answer given, the API will either fetch the Model or the make from the datasource and return it as an outcome.

Click on the ‘Export.rbird’ button to download the ‘Rule Types’ map used in this example. The knowledge map can then be imported into your Rainbird Studio.

Query and Result

The query is build as usual on the rule ‘gets’. The evidence tree shows the retrieved data from the external data source in green.

Article Feedback form
Did you find this article useful?