REST API v5 Tutorial (deprecated)

The REST Auto API lets you work with car data on any platform. This tutorial will help you get started and show you how to work with it. By following the steps you will be receiving odometer data from the car simulator.

Endpoint URL

Note that the REST API base URL is when working with the car emulators and for live vehicle data.

When you use the configuration snippets from the platform as shown in this tutorial, you will always be using the right URL automatically.

Create a Cloud App

In "Develop mode" you will find your sandbox apps. In the app details page you are going to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. Let's see how to create a new app.

  1. Go to the Build tab, select "Develop mode" and click the big plus (+) button, select "Fleet" or "Driver" as the type and then select "Cloud App".
  2. In the left section, select the permissions that your app needs under the "Permissions" tap.
    Note: Each permission must be manually added to each new app.
  3. You can edit your app name and image from the menu icon next to the app name.

Create a Vehicle

In the "Simulation studio" you are able to create vehicles to link with your app and to test with the simulators. Go to the simulation studio and click the big plus (+) button.

Get API Config

The first thing your app code needs to do is to provide credentials to the server. This is done through JWT and we will provide an example in this tutorial for JavaScript.

  1. Go to the Build tab, and select the app you created in the previous steps.
  2. Choose "Client certificate" in the left section and then the "REST" tab.
  3. Copy the JSON snippet.
  4. Insert the snippet into into your project and assign it to a variable.

The config variable will look something like this:

  version: '3.0',
  type: 'rest_api',
  private_key_id: 'fdfa4bf6-328b-4c82-b6e0-833688690acb',
  private_key: `-----BEGIN EC PRIVATE KEY-----
-----END EC PRIVATE KEY-----`,
  app_uri: '',
  client_serial_number: '0DF5997A3A2E151C7B'

Here's an overview of the steps:

  1. Include the key-pair information in your back-end system. You can use your preferred JWT library.
  2. Create an JWT Token per example below.
  3. The second step has to be done for all endpoints, e.g. getting the diagnostics state.

Create a JWT

The JWT should be signed using the ES256 algorithm and must contain the following claims:

verThe version of the API, taken from the version field in the config
audThe API URI, taken from the app_uri field in the config
issA unique serial number, taken from the client_serial_number field in the config
iatThe current datetime, formatted in the Unix timestamp format. This is used to minimize the possibilities of a replay attack, so that a JWT created in the past cannot be reused. Currently a tolerance of 30 seconds is used to account for any clock skew between our servers and the back end servers, but it can be changed, probably shortened in the future. Example value: 1502121268
jtiAn unique identifier in the UUID format of the JWT itself to ensure a JWT can be used only once.
subThe access token specific to the car, the retrieal of which is done through OAuth2 or the Service Account API for fleet vehicles

Send a Request

Once the simulator is open, fire away a request. For example to get the diagnostics state of the vehicle.

If you see that the app lacks permissions, you will need to revisit step two of the "Create an App" section of this document and select the appropriate permissions for your telematics command.

Auto API

Check out the Auto API OpenAPI Specification for all details.

const request = require('request')

  url: REST_API_CONFIG.app_uri + '/diagnostics',
  headers: {
    Authorization: 'Bearer ' + jwtToken
}, (error, response, body) => {
  console.log('error:', error)
  console.log('statusCode:', response && response.statusCode)
  console.log('body:', body)