API

The following describes the Application Programming Interface (API) of the Safety Pool™ Scenario Database (SPSD), which can be used by authorised systems to access the data within the database that has been made available to access.

How to use the API

In order to use the API, your organisation will have need to have registered to use the SPSD and have an account setup on the SPSD for your organisation.

The API is a Restful API that has been implemented using the standard HTTP protocols which means that it is easily accessible using a variety of tools and programming languages; tools such as Postman can be used to test communicating with the API.

The API has been documented using a combination of OpenAPI to describe the API methods, and a JSON Schema to describe the data returned by the API methods, the reason for this being that OpenAPI is not yet able to sufficiently describe the schema of the JSON data returned from the API. Click here for the OpenAPI definitions and JSON Schema.

The root location of the API is at: https://live.safetypooldb.ai/api. The API is only accessible via HTTPS and requires TLS v1.2 or higher. Currently, the API only allows read-access to the database.

For technical support, please contact support@safetypooldb.ai

Enabling and Disabling API Access

Before the API can be used, the System Administrator for the organisation to be accessed has to enable API access by logging into the SPSD, and then going into Settings and clicking ‘Enable Access’.

SPSD User Interface for enabling API access

 This will then generate a unique API Key which will need to be passed to the API in order to use it. The API Key is unique to the organisation for which it has been created and should be stored in a secure way to prevent unauthorised access to the database. Note that the API Key cannot be used to log into the SPSD via the User Interface.

SPSD User Interface for disabling API access

 If API access is no longer required then it is recommended to disable API access by going into Settings and clicking ‘Disable Access’. Note that if API access is re-enabled then a new API key will be generated, and so any existing systems which have API access will need updating with the new key.

Authentication

In order to use the API to access data, an API Key must have been obtained first. The API Key is used to authenticate callers to the API.

The API methods which access data are secured and require a JWT Bearer token to be passed with each request.

To start a session, the createtoken2 method must be called with a valid API Key passed in the request body.

This will return a JSON object which contains a token which must then be passed as a bearer token on subsequent calls to secured API methods. The token will expire after a set period time which can be found in the JSON object returned by the createtoken2 method.

Accessing Data

There are two types of data which can be accessed via the API: Scenarios and Test Suites.

The API can be used to access all of the Scenarios and Test Suites defined for the organisation being accessed as well as Scenarios and Test Suites held in Public Libraries.

Note: care should be taken when accessing data that requests are only made for data to which the organisation is allowed to access, otherwise this might be detected as an attempt to gain unauthorised access to data and API access will temporarily be disabled for a few minutes.

Accessing Scenarios

Retrieving a Scenario

To retrieve a scenario from the database, the following method should be called:

The method requires that the scenarioId of the scenario is passed to it. The scenarioId is the unique identifier of the scenario which is a Universally Unique ID (UUID), and corresponds with the URN field visible in the Scenario View in the UI. Other API methods also return ScenarioId’s which can be used as input to this method.

The method returns a JSON object that conforms to the ASAM OpenLABEL standard. 

It contains the scenario definition and tags describing the scenario. Click here for a full details on the data returned.

Retrieving Scenario Files

Within the SPSD, it is possible to upload files and associate them with scenarios, for example, OpenScenario and OpenDrive files can be uploaded to provide an alternative definition of a scenario which can be useful in a situation where a testing toolchain does not support WMG SDL.

To obtain a list of files which are associated with a scenario, the following method should be called:

The method will return a list of file references which can be used to retrieve files using the following method:

Accessing Test Suites

Retrieving all Test Suites

If an external system requires a user to be able to select a Test Suite from a list of existing test suites, then the following method can be called in order to get a list of test suites applicable to the organisation being accessed which will include all of the Test Suites the organisation has created as well as Test Suites existing in public scenario libraries.

The test suite data returned will include a unique identifier for each test suite that can be used in other API methods to retrieve further data related to the test suite.

Retrieving a Test Suite

To retrieve a Test Suite from the database, the following method should be called. The testsuiteId parameter can be obtained from having previously retrieved the list of all test suites, or can be found in the SPSD UI by viewing a Test Suite and making a note of the Test Suite ‘External Ref’ field.

The method returns a JSON object which contains details about the Test Suite and includes a references to the scenarios associated with the TestSuite. The scenario definitions can be retrieved by calling the scenario get method.

If within the SPSD, route testing locations have been selected for the scenarios in the Test Suite, then a route testing location for each scenario will be present in the returned JSON object. The testing location will include a name of the location and also a geographic definition of the route location defined by a GeoJSON Feature object. GeoJSON can be rendered onto a map using tools such as Leaflet.js.

Note: Route test location data is not currently available.

Safety Pool Scenario Database Tagging Ontology

The following method will return the Safety Pool tagging ontology in Turtle format. The ontology is useful when processing scenario tags contained in OpenLabel files downloaded from the database.