IoT Edge Connect Message Store API v1

Provides a storage service for uploading, managing, and downloading content from a key-value datastore.

Learn more:


Overview

The IoT Edge Connect Message Store API provides an HTTP mechanism to upload, download, and manage your content in a secure, key-value data store service.

In key-value data stores, also known as data sets, you can represent an object by an arbitrary string such as a filename or a hash. The matching value can be any type of data, such as files, images, or documents.

Use this functionality to upload and manage content, and then easily download it to a device. For instance, you can upload map tiles, documents, or firmware updates that you can later access and download to a vehicle head unit.

This service runs on the globally scalable Akamai Intelligent Platform. It offers on-demand capacity and global geographical replication with reliable server mapping and routing technology.

Designed for constant availability, the IoT Message Store API offers many essential features lacking in today’s cloud-based storage solutions, all without investing in and maintaining dedicated storage servers.

Who should use this API

Use this API to upload, access, and manage objects in your key-value data store. You can simply upload objects up to 4 GB to a designated data set, get the contents or metadata of objects, and remove objects from the data store.

The platform replicates the content across edge servers for reliability.

This API corresponds to the Edge Connect Message Store application that you can use for data store configuration and management.

Get started

To use this API for the first time:

Authentication

This API doesn’t use Akamai’s EdgeGrid authentication and doesn’t rely on the standard system of provisioning API tokens within Akamai Control Center.

You can either authenticate access to your data on the origin’s part, or use the authentication method you configured for your Edge Connect Message Store property:

  • For JWT, you need to pass the token in your request header. Unless you’ve specified otherwise, the header name is X-Akamai-Auth-Token. You can also pass your token in the URL auth parameter. See IoT Token Access Control.

  • For Mutual Authentication, your authentication validates alongside your connection to the service. You don’t need to pass any authentication information in your request.

API concepts

To understand this API’s various URL resources and the data it exchanges, familiarize yourself with these concepts:

  • Property. A property, also referred to as a configuration, controls how edge servers respond to various kinds of requests to your assets. Properties apply rules to a set of hostnames, and you can only apply one property at a time to any given hostname. Each property is assigned to a product, which determines which rule behaviors you can use. You can manage properties from Property Manager or the Property Manager API.

  • Database. A top-level storage unit that can contain one or more data sets. Each property can have several databases.

  • Data set. A storage unit associated with a database. It stores a collection of key-value objects. Each database within a property can include several data sets.

  • Object or Message. A key-value object stored in a data set. Within a message, a key serves as a unique identifier to get the value. The matching value can be any type of data, such as a file, an image, or a document. See the Object response.

Workflow

You can run the Upload an object operation to upload a single object to a data set.

You can run these operations to download objects from your data set or to get object metadata:

  • Run the List object keys operation to get object keys stored in the data set.

  • Run the Get an object operation to download the contents of an object. See Object paths.

  • Run the Get object metadata operation to obtain metadata, such as headers and MD5 hashes, to verify your upload and optimize caching.

You can run these operations to delete objects from your data set:

Object paths

In this API, you can dynamically configure endpoint path URLs and adjust them to specific use cases. For instance, you can map URLs when a device is already configured to use a specific path.

For the default configuration, the base for every path consists of a hostname and a /datastore segment. Your hostname, for instance, might be downloads.automotive-company.akamai.com. You can check the hostnames on your account by running the List edge hostnames operation in the Edge Hostnames API.

The endpoint paths depend on the database and data set location parameters you set in the Message Store database and Message Store data set selection behaviors.

You can match these behaviors to filter requests using PCRE-style regular expressions. For this, you can use rule templates for custom path configuration such as Message Store Upload in Property Manager or the Property Manager API.

If you choose to pass both the database and data set names in your request’s headers, as in the default configuration, the endpoint HTTP path for the Get an object operation follows the {hostname}/datastore/{key} format. Choosing query string parameters as the location for passing database and data set names requires the {database} and {dataset} names as query parameters in the endpoint path, as in {hostname}/datastore/{key}?database={database}&dataset={dataset}. See the API summary for default operation paths.

Consider these examples with sample values:

  • downloads.automotive-company.akamai.com as the hostname
  • AAX.dat as the object key
  • db1 and ds1 as the database and dataset names
Message Store database location Message Store data set location Endpoint path format Endpoint path example
Header Header {hostname}/datastore/{key} downloads.automotive-company.akamai.com/datastore/AAX.dat
Query string parameter Header {hostname}/datastore/{key}?database={database} downloads.automotive-company.akamai.com/datastore/AAX.dat?database=db1
Header Query string parameter {hostname}/datastore/{key}?dataset={dataset} downloads.automotive-company.akamai.com/datastore/AAX.dat?dataset=ds2
Query string parameter Query string parameter {hostname}/datastore/{key}?database={database}&dataset={dataset} downloads.automotive-company.akamai.com/datastore/AAX.dat?database=db1&dataset=ds2

If the path in your request doesn’t match your property configuration, the default database you chose in the Message Store database and Message Store data set selection behaviors overrides it.

Add custom headers

IoT Message Store API lets you add up to ten custom headers to the objects you store for troubleshooting, informational purposes, or implementing particular logic on the client’s or device’s side.

You can create your custom headers by following the X-AK-Meta-* pattern. Your headers can be up to 128 characters long, and their values can be up to 64 characters long.

For instance, you can use of the X-AK-Meta-Permission header to allow only a specific group of users to access your objects, or create a custom header to control device behavior after downloading a file.

Resources

This section provides details on the IoT Edge Connect Message Store API’s various operations and parameters.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List object keys GET /datastore{?from_name,limit}
Delete all objects DELETE /datastore
Get an object GET /datastore/{key}
Delete an object DELETE /datastore/{key}
Get object metadata HEAD /datastore/{key}
Upload an object PUT /datastore/upload/{key}

List object keys

Returns the names of objects stored in your data set in alphabetical order. You can use the fileName value from the response as object

GET /datastore{?from_name,limit}

Sample: /datastore?from_name=AAX&limit=10

Parameter Type Sample Description
Optional query parameters
from_name String AAX Returns messages with keys greater or equal to from_name from all available messages in alphabetical order.
limit Integer 10 Limits the number of objects in the response. By default, you receive 1000 objects, and the maximum value is 10000.

Status 200 application/json

Object type: Object

Download schema: BulkListMessages.json

Response body:

[
    {
        "fileName": "AAX.dat",
        "size": 864421
    },
    {
        "fileName": "ABD.dat",
        "size": 463422
    }
]

Delete all objects

Deletes all objects stored in a data set. If you want to purge the cache every time after deleting or modifying objects, enable the purge option in the Message Store caching behavior in your property.

DELETE /datastore

Status 204

Get an object

Returns the contents of the object stored under the specified key in your data set. If you don’t already have the key value for the object, run the List object keys operation, select a fileName from the response object, and use it as the key in your request. You can also use the Range header to indicate the part of the object that you want to receive. In the response, this operation returns the Content-Type header for the object and any custom X-AK-Meta-* headers you set with the Upload an object operation.

GET /datastore/{key}

Sample: /datastore/AAX.dat

Headers:

If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT
If-None-Match: 686897696a7c876b7e
Range: bytes=0-499
Parameter Type Sample Description
URL path parameters
key String AAX.dat The unique key value for an object stored in the data set. It can be up to 64 characters long.

Status 200

Headers:

Content-Type: image/png
X-AK-Meta-*: X-AK-Meta-Permission

Status 206

Headers:

Content-Type: image/png
X-AK-Meta-*: X-AK-Meta-Permission

Status 304

Delete an object

Removes the object stored under the specified key from your data set. If you don’t already have the key value for the object, run the List object keys operation, select a fileName from the response object, and use it as and use it as the key in your request.

DELETE /datastore/{key}

Sample: /datastore/AAX.dat

Parameter Type Sample Description
URL path parameters
key String AAX.dat The unique key value for an object stored in the data set. It can be up to 64 characters long.

Status 204

Get object metadata

Returns the object’s metadata without downloading its contents. You can view the Content-Type, Content-MD5, Content-SHA256, and ETag headers set for the object. Use the MD5 hash and SHA256 values to verify your upload, and the Last-Updated timestamp to optimize caching. You can also view the custom X-AK-Meta-* headers you set with the Upload an object operation. If you don’t already have the key value for the object,

HEAD /datastore/{key}

Sample: /datastore/AAX.dat

Headers:

If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT
If-None-Match: 686897696a7c876b7e
Parameter Type Sample Description
URL path parameters
key String AAX.dat The unique key value for an object stored in the data set. It can be up to 64 characters long.

Status 200

Headers:

Content-Type: application/octet-stream
Content-MD5: 1a79a4d60de6718e8e5b326e338ae533
Content-SHA256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15
ETag: 686897696a7c876b7e

Upload an object

Uploads an object under the specified key and sets the object’s headers. In case of simultaneous uploads to the same key, the upload with the last written byte wins. Set the Content-Type header to specify the media type for the object. You can use an MD5 or SHA256 hash as the ETag header for this version of the object to optimize caching. Use the Expires header to specify the time after when the object expires and is automatically deleted. With this operation, you can also set custom headers for the specified object. See Add custom headers.

PUT /datastore/upload/{key}

Sample: /datastore/upload/AAX.dat

Headers:

X-AK-Meta-*: X-AK-Meta-Permission
Content-Type: image/png
ETag: 686897696a7c876b7e
Expires: Wed, 21 Oct 2015 07:28:00 GMT
Parameter Type Sample Description
URL path parameters
key String AAX.dat The unique key value for an object stored in the data set. It can be up to 64 characters long.

Status 200

Headers:

Content-MD5: 1a79a4d60de6718e8e5b326e338ae533
Content-SHA256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15
Content-Type: application/octet-stream

Status 201

Headers:

Content-MD5: 1a79a4d60de6718e8e5b326e338ae533
Content-SHA256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15
Content-Type: application/octet-stream

Data

This section provides details for each type of data object the API exchanges.

Object

Provides basic information about the objects stored in your datastore.

Download schema: BulkListMessages.json

Sample GET response:

[
    {
        "fileName": "AAX.dat",
        "size": 864421
    },
    {
        "fileName": "ABD.dat",
        "size": 463422
    }
]

Object members

Member Type Required Description
Object: Provides basic information about the objects stored in your datastore.
fileName String The name under which the object is stored in the dataset. You can use the fileName value from the response as object keys for the Get an object, Delete an object, and Get object metadata operations.
size Integer The size of the object in bytes.

Errors

Unlike other Akamai APIs, this API doesn’t return any data with error responses. This section lists only the response status codes for error and success cases for this API.

HTTP status codes

This API responds with the following range of status codes for both success and failure scenarios:

Code Description
200 The object has been successfully updated.
201 The object has been successfully uploaded.
204 The object has been deleted.
206 Successful request. The body now contains the requested Content-Type or X-AK-Meta-* headers.
304 Request conditions matched. No need to retransmit the data.
400 Bad request.
401 Unauthorized request. See Authentication for reference.
404 Object not found.
503 Service unavailable.