v2.0 changelog

This changelog contains all major updates and feature additions to version 2.0 of Smartcar’s APIs.

v2.0 SDK methods

If you are using one of our SDKs, please add the following code block to specify that all requests should be made to v2.0 of the Smartcar API.

Note: It’s best to invoke the method from a “central” part of your codebase, as the helper method only needs to be invoked once rather than before every API request.

const smartcar = require('smartcar');

smartcar.setApiVersion('2.0');

If you are not using any of our SDKs, simply replace /v1.0/ with /v2.0/ in the URLs that you construct.

Compatibility

The Compatibility API has been updated to return a more detailed response that provides an endpoint-by-endpoint breakdown of what the vehicle is capable of.

The previous version of the Compatibility API returned a single field named compatible, which encapsulated both the vehicle’s compatibility with Smartcar and the vehicle’s capability to carry out all of the permissions that were passed into the scope parameter. This new version of the Compatibility API breaks this single field down into the following fields:

• compatible: Does the vehicle have the required hardware for internet connectivity and does it belong to the set of makes and models that Smartcar is compatible with?

  Note: The meaning of this field has changed compared to v1.0.

• capabilities: A list of the endpoints that the permissions passed into the scope parameter provide access to. Each entry has a field named capable that indicates whether the vehicle capable of supporting that specific endpoint.

Example

{
  "compatible": true,
  "reason": null,
  "capabilities": [
    {
      "permission": "read_battery",
      "endpoint": "/battery",
      "capable": true,
      "reason": null
    },
    {
      "permission": "read_battery",
      "endpoint": "/battery/capacity",
      "capable": false,
      "reason": "VEHICLE_NOT_CAPABLE"
    }
  ]
}

Migration Steps

The simplest migration path would entail replacing mentions of compatible with a logical AND between compatible and capabilities[].capable. However, we recommend modifying your application logic to make use of the more detailed information that the new version of the Compatibility API offers.

We recommend using logic similar to the following:

1. If compatible is false, use the reason field to let the user know that their vehicle is not compatible because it does not have the required hardware (reason = VEHICLE_NOT_CAPABLE) or because their vehicle is not yet supported (reason = UNSUPPORTED_MAKE).
2. Iterate through the list of capabilities to check whether the vehicle is capable of the endpoints that your application requires. While iterating through the list, collect the subset of permissions that the vehicle is capable of.
3. Launch Connect with scope set to the list of permissions that the vehicle is capable of.

Errors

We updated the errors returned by Smartcar’s API and webhooks to include a lot more detail. We also introduced new error types and codes to let developers more easily investigate Smartcar errors.

Smartcar errors now contain the following properties:

Migration steps

1. Reference body.type instead of body.error.
2. Reference body.description instead of body.message.
3. Make use of the new values of type and code rather than the old values by referencing the mapping in the table below. Note that some version 1.0 errors map to multiple version 2.0 errors, as version 2.0 contains more detailed errors.

Webhook verification

The verification payload now includes the ID of the requested webhook. It also includes an eventName property that lets you distinguish verify events from other webhook events. For verify events, the eventName property will be set to “verify”. The challenge property is now nested under a payload property.

{
  "version": "2.0",
  "webhookId": "uuid",
  "eventName": "verify",
  "payload": {
    "challenge": "string"
  }
}

Migration steps

1. Reference body.payload.challenge instead of body.challenge.
2. (Optional:) Use body.eventName to detect a webhook verification request rather than checking for the presence of the challege property.

Webhook event payloads

The vehicles property is now nested under a payload property.

{
  "version": "2.0",
  "webhookId": "uuid",
  "eventName": "schedule",
  "mode": "test|live",
  "payload": {
    "vehicles": []
  }
}

Migration steps

1. Reference body.payload.vehicles instead of body.vehicles.