IoT OTA Updates API v1

Securely update vehicle-specific software over cellular networks.

Learn more:


Overview

Part of the Internet of Things (IoT) product, the OTA Updates module enables automotive companies to leverage the Akamai Intelligent Platform to provide a highly scalable, secure, and reliable mechanism to perform updates of most-up-to-date versions of software to vehicle head units over a cellular network.

The OTA Updates solution also supports a reporting mechanism centered on download functions. It provides automotive customers with individual vehicle and aggregated reports, allowing them to log and aggregate download data for individual vehicles or by additional dimensions such as make or model.

The OTA Updates API provides you with a list of completed downloads by vehicle, limited only to those downloads associated with a content provider code. A completed download is defined by the download complete marker behavior and its match criteria while configuring the OTA Updates property. To configure download traffic, use the Property Manager within Luna Control Center, or the equivalent Property Manager API.

Who should use this API

Use this API if you want to view a list of completed downloads by vehicle.

Before using the Beta API for the first time:

  • Review Get Started on tools that Akamai provides for all its APIs.

  • Review Authorize Your Client to create your API access credentials and authorizations. As detailed in the The API Identity Model section, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

Resources

This section provides details on the OTA Updates API’s various operations and parameters.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
CP Codes  
List Content Provider Codes GET /ota/v1/cpcodes
Download Notifications  
List Download Notifications GET /ota/v1/download-notifications/{cpcode}{?start}

List content provider codes

This operation lists all content provider codes assigned to the Internet of Things product. Use one of the identifiers as input to the List Download Notifications operation.

GET /ota/v1/cpcodes

Status 200 application/json

Response Body:

[
    {
        "id": 100001,
        "name": "cp code 100001"
    },
    {
        "id": 100002,
        "name": "cp code 100002"
    }
]

List download notifications

This operation returns a single page of notifications about completed downloads to specific vehicles, limited to those downloads registered under one content provider code. All requests subsequent to the first request require storing nextPageStart from the last response’s notifications array and using it as start of a new request.

GET /ota/v1/download-notifications/{cpcode}{?start}

Sample: /ota/v1/download-notifications/100001?start=1497947550000

Parameter Type Sample Description
URL parameters
cpcode Integer 100001 The content provider code assigned to the Internet of Things product. Run the List Content Provider Codes operation to get an identifier.
Optional query parameters
start Integer 1497947550000 The Unix timestamp in milliseconds that starts a range of notifications. It cannot be older than the notification retention period of the past 12 hours. If not specified, the API returns notifications from the past 12 hours.

Status 200 application/json

Response Body:

{
    "notifications": [
        {
            "cpcode": 100001,
            "downloadTime": "2017-05-16T17:30:01+00:00",
            "uid": "0000-0000-0001",
            "host": "downloads.automotive-company.com",
            "path": "/files/0001"
        },
        {
            "cpcode": 100001,
            "downloadTime": "2017-05-16T17:33:02+00:00",
            "uid": "0000-0000-0002",
            "host": "downloads.automotive-company.com",
            "path": "/files/0002"
        }
    ],
    "nextPageStart": 1497627402001
}

Data

This section provides details on the API’s JSON objects, which report available CP codes and details on completed downloads by vehicles. The response data provided associates downloaded files with vehicles, along with the CP codes provisioning the download traffic.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.

NotificationList

Encapsulates a collection of download notifications, with additional pagination context.

Download schema: notifications.json

Sample GET response:

{
    "notifications": [
        {
            "cpcode": 100001,
            "downloadTime": "2017-05-16T17:30:01+00:00",
            "uid": "0000-0000-0001",
            "host": "downloads.automotive-company.com",
            "path": "/files/0001"
        },
        {
            "cpcode": 100001,
            "downloadTime": "2017-05-16T17:33:02+00:00",
            "uid": "0000-0000-0002",
            "host": "downloads.automotive-company.com",
            "path": "/files/0002"
        }
    ],
    "nextPageStart": 1497627402001
}

NotificationList members

Member Type Required Description
nextPageStart Integer The timestamp in milliseconds that indicates the start of the next page of notifications.
notifications NotificationList.notifications[] Encapsulates each download notification.
NotificationList.notifications[]: Encapsulates each download notification.
cpcode Integer The content provider code under which traffic is billed.
downloadTime String The date and time of a download event on a Ghost server.
host String The host of a downloaded file.
path String The path of a downloaded file.
uid String The unique identifier of a vehicle.

CpCode

Specifies a content provider code.

Download schema: cpcode.json

Sample GET response:

[
    {
        "id": 100001,
        "name": "cp code 100001"
    },
    {
        "id": 100002,
        "name": "cp code 100002"
    }
]

CpCode members

Member Type Required Description
id Integer The identifier of the content provider code.
name String The name of the content provider code.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

This API responds with HTTP Problem Details error objects. This sample shows an incorrect request error, where details explain why the error occurred and incidentId may be useful if you need to communicate about the problem with your Akamai support representative:

{
    "details": [
        {
            "code": "unreadable.value",
            "message": "Unreadable value: 'xxxx' passed",
            "data": {
                "value": "xxxx"
            }
        }
    ],
    "code": "bad.request",
    "title": "Bad Request",
    "incidentId": "808ccc7c-a36f-4a64-ae18-5d09bfab91fd"
}

HTTP status codes

The API responds with the following set of HTTP status codes for both success and failure scenarios.

Code Description
200 The operation was successful.
400 Bad Request.
401 Unauthorized access.
403 Access is forbidden.
500 Internal server error.

Last modified: 1/12/2018