Auto API Level 12 Is Now Live

Update: Auto API 13 is released, learn more here.

What's new

The full change log is linked at the bottom of this post, and details every update to the protocol. Here are the highlights:

New properties have been added, increasing the total catalogue size to 436 data points. Each new property is noted in the change log; the new properties expand capabilities such as charging, diagnostics, maintenance, theft alarm, trips, and usage.
VIN (Vehicle Identification Number) and vehicle brand have been removed from the Vehicle Status and added as global properties. Going forward, the two properties are included in any API response.
So far the Auto API has always provided data according to the metric system. It now does not need any conversion but instead returns the unit along with the property value. That way the value can be handled just as it is put together in the vehicle.
The unit of measurement will now be included in API responses. Until now, the Auto API has provided data measured in metric units, but without specifically stating the unit in the response. Now, the value and unit are returned together, so there is no question about which unit is being used.
Each property now has an availability component. This means that it’s possible to determine how often a vehicle typically refreshes a certain data point. The API now also provides information about any rate limit there might be when querying a given property.
The Capabilities API is now able to provide a list of webhooks available for a given vehicle. It can still provide information about available properties.
Some properties have been deprecated. One important change to mention is the deprecation of mileage, which has been replaced by odometer. The odometer property should be used from now on.

Updates in the High Mobility platform

We have put the many updates in Auto API Level 12 to use in our platform to enable new features both for production vehicles and for the vehicle emulator. Here is a breakdown of the upgrades for each major component.

Introducing REST API v4

The fourth version of the REST API includes a host of changes, all of which are detailed in the change log. The new API is accessed by changing the version number in the end of the URL: https://rest-api.high-mobility.com/v4
Here is an example data returned by the Diagnostics capability. Note the inclusion of units, which did not appear in v3 of the REST API. Other changes are limited to property names and deprecations. Please consult the change log to see if there is any impact on your application.

‍

‍

To check for the availability of the Diagnostics properties, you can use the new diagnostics/availability endpoint.

Here’s an example when checking the estimated range availability:

‍

‍

The OpenAPI specification of REST API v4 can be found in our documentation and the raw YAML file is on GitHub.

iOS SDK updates

The new version of the Swift Auto API library is 12.0.0, and the integration is done the same way as before. The version must be changed in the Package.swift file (or in Xcode project settings) to reflect the update:

‍

‍

Other changes include Measurement<Type> for properties with units, as well as availability API and the other updates mentioned above.

Android SDK updates

The new version of the Java Auto API library is 3.12.0, and it can be added to any Android project manifest as a dependency:

‍

‍

The main SDK interface update is the handling of both the data value and unit. Previously, only the value was returned. Now a data property also has the unit attribute and convenient methods to check the unit:

‍

‍

Node.js SDK updates

The latest version of the Node.js SDK 12.0.0 can be installed with Node Package Manager:

‍

‍

The usage of the SDK has not changed in other aspects besides the updated Auto API version. The JSON example of REST API v4 shows the structural update of the data that is returned by the SDK.

‍

Impact on Production Mode

REST API v3 will continue to work in production mode until April 1st, 2021, in order to give you time to update to the new API version. The updates in the API definitions are minor and we are glad to support you in any way during your migration.

New car simulator features

The simulator supports all the new additions in Auto API Level 12. There is now an “Advanced options” button which allows you to configure the behaviour of the property.

‍

‍

With Advanced options, the following can be configured:

The unit used to measure a value
The update rate, i.e. how often the vehicle refreshes the property
The rate limit, which indicates how often it is possible to query the specific property
Failure message, if the data can not be returned for some reason. In these cases the failure component of the property is returned instead of a value

‍

‍

All of the above can also be configured within a trip simulation. It is important to note that from now on, the emulator will only support Auto API Level 12. This means that REST API v4 and the Level 12 SDK libraries must be used.