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.
6. Staying on the ‘Add Datasource’ menu, add the following URL to the API Request box:
https://uk1.ukvehicledata.co.uk/api/datapackage/VehicleAndMotHistory?v=2&api_nullitems=1&auth_apikey=YOUR_API_KEY&key_VRM=VEHICLE_NUMBER
Figure 4: API request
The URL comprises:
- The hostname: https://uk1.ukvehicledata.co.uk/
- The path: api/datapackage/VehicleAndMotHistory
- Different parameters:
- v : 2
- api_nullitems : 1
- auth_apikey : YOUR_API_KEY
- key_VRM : VEHICLE_NUMBER
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’
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 Varibles 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.
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.
