REST API Tutorial
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.
Endpoint URL
Note that the REST API base URL is https://sandbox.rest-api.high-mobility.com/v5 when working with the car emulators and https://rest-api.high-mobility.com/v5 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 the Develop tab you will find your 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.
- Go to the Develop tab, click the big plus (+) button and select Cloud App. Enter a name and continue.
- In the left section, select the permissions that your app needs under the "Permissions" tap. For the purporses of this tutorial, you will need to select the "Diagnostics" capability and then select "Get odometer" before pressing "save".
Note: Each permission must be manually added to each new app. - You can edit your app name and image from the menu icon next to the app name.
Create a Vehicle
In the carmaker workspaces you will be able to create vehicles or other items to link with your app and to test with the emulators.
- Go to a carmaker workspace, click the big plus (+) button and select one vehicle to start. Enter a name and continue.
- You will find the vehicle capabilities listed to the left.
- If you click on the "Launch emulator" button you will see how it looks like. Next we will need to link an app with the vehicle.
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.
- Go to the Apps tab, and select the app you created in the previous steps.
- Choose "Client certificate" in the left section and then the "REST" tab.
- Copy the JSON snippet.
- Insert the snippet into into your project and assign it to a variable.
The config variable will look something like this:
const REST_API_CONFIG = {
version: '3.0',
type: 'rest_api',
private_key_id: 'fdfa4bf6-328b-4c82-b6e0-833688690acb',
private_key: `-----BEGIN EC PRIVATE KEY-----
MHYCAQEEIOWpew43ebg4jS0vAaXGFjBFmpZRb2f8KIampd2Emi25oAoGCCqGSM49
AwEHoUMDQQCE8W3k3aprpBxZ3QBlW+WdteJc+UgeIyqY/UOOAcR4qanZKj6CBHa3
8Wl60x6ql2IESr8F3ZXRnVIami0VC7mY
-----END EC PRIVATE KEY-----`,
app_uri: 'https://sandbox.rest-api.high-mobility.com/v5',
client_serial_number: '0DF5997A3A2E151C7B'
}
Here's an overview of the steps:
- Include the key-pair information in your back-end system. You can use your preferred JWT library.
- Create an JWT Token per example below.
- 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:
| ver | The version of the API, taken from the version field in the config |
| aud | The API URI, taken from the app_uri field in the config |
| iss | A unique serial number, taken from the client_serial_number field in the config |
| iat | The 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 |
| jti | An unique identifier in the UUID format of the JWT itself to ensure a JWT can be used only once. |
| sub | The access token specific to the car, the retrieal of which is done through OAuth2 or the Service Account API for fleet vehicles |
Link Vehicle and Retrieve Access Token
Production mode
In order to get an Access Token for a production app, either the OAuth2 consent flow or the Fleet Clearance documentation should be followed.
Now you just need to link the vehicle with the app in order to work with it in the emulator. Follow the next steps:
- Go back to your app details page in the Apps tab and click on the "Create link" button on the right side.
- Choose the vehicle you just created and link it to your app. The vehicle will be added to linked vehicles list but you will see an alert icon between the app and the vehicle. That means that your app has yet not been authorised.
- Click on the alert icon and you will see an Access Token snippet that is unique to this link. Copy it.
- Insert the snippet into your project code use it in combination with your app config to create a JWT Token.
- Click on the vehicle to launch the emulator. This time you can start using your app to interact with the vehicle's APIs.
The code snippet in your project should look something like this:
const jwt = require('jsonwebtoken')
const uuid4 = require('uuid4')
const payload = {
ver: REST_API_CONFIG.version,
iss: REST_API_CONFIG.client_serial_number,
aud: REST_API_CONFIG.app_uri,
iat: Math.round(Date.now() / 1000),
jti: uuid4(),
sub: 'b55af95a-607c-47e8-ad37-5016a8beda61',
}
const privateKey = Buffer.from(REST_API_CONFIG.private_key, 'utf8')
const jwtToken = jwt.sign(payload, privateKey, { algorithm: 'ES256' })
Send a Request
Once the emulator is open, fire away a request. For example to get the diagnostics state of the vehicle. Note that you will get a "Vehicle Asleep" error returned if the emulator is closed.
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')
request.get({
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)
})