io7m | single-page | multi-page | epub | Stonesignal User Manual 1.0.0-beta0001
7.1. Admin API 1.0
Previous
7. API Access
Up
7.3. Data API 1.0
Next

# 7.2. Device API 1.0

- 7.2.1. Overview
- 7.2.2. Formats
- 7.2.3. Authentication
- 7.2.4. Errors
- 7.2.5. Endpoint: /
  - 7.2.5.1. Description
  - 7.2.5.2. Request Type
  - 7.2.5.3. Response Type
  - 7.2.5.4. Example
- 7.2.6. Endpoint: /device-location-put
  - 7.2.6.1. Description
  - 7.2.6.2. Request Type
  - 7.2.6.3. Response Type
  - 7.2.6.4. Example

## 7.2.1. Overview

1
The device API is the API used to accept location data from devices.
2
The API is designed as a set of HTTP endpoints with which clients exchange messages in a strictly-defined and versioned JSON (or, optionally, CBOR-encoded) format.
3
There is no version negotiation in the protocol. Clients must check to see which versions are available using the version document, and then speak directly to the versioned endpoints using the correct protocol version.

## 7.2.2. Formats

1
The API endpoints allow for communicating in a number of different formats that each use the same underlying data model. If a client specifies a Content-Type header with a request, the server will respond using the same format.
2
All API endpoints will accept a Content-Type header that must be one of the following values:

### 7.2.2.3. Format Values

Format | Description
--- | ---
application/stonesignal+json | The textual JSON format.
application/stonesignal+cbor | The binary CBOR format.

4
If no Content-Type header is provided, application/stonesignal+json is assumed.

## 7.2.3. Authentication

1
Clients must include an Authorization header with a value of Bearer k, where k is the assigned device key.
2
All endpoints require authentication except for the root endpoint.

### 7.2.3.3. Example

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 02210D83680AC0F4A50C47F51DCCE35610DE59717623A0D9408067279A63D511' \
      http://example.com/1/0/device-location-put

## 7.2.4. Errors

1
All endpoints return a 200 HTTP status code on success with an endpoint-specific response message. On errors, all endpoints return an HTTP status code greater than or equal to 400 with a response conforming to the following schema:

### 7.2.4.2. Error Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "type" : "object",
      "properties" : {
        "ErrorCode" : {
          "type" : "string",
          "description" : "The error code."
        },
        "Message" : {
          "type" : "string",
          "description" : "The human-readable error message."
        }
      },
      "required" : [ "ErrorCode", "Message" ]
    }

3
As an example:

### 7.2.4.4. Error Schema

    $ curl -s http://example.com/1/0/device-location-put | jq
    {
      "ErrorCode": "error-401",
      "Message": "Unauthorized"
    }

## 7.2.5. Endpoint: /

## 7.2.5.1. Description

1
The / endpoint exposes a ventrad version document that explains which API versions are available and where they are hosted.
2
The Endpoint property of each protocol defines a prefix that must be included in order to reach the correct endpoint. So, for example, if the Endpoint property is /1/0, then the /device-location-put endpoint would be reachable at /1/0/device-location-put.

## 7.2.5.2. Request Type

1
The endpoint ignores any request data.

## 7.2.5.3. Response Type

1
The endpoint responds with a ventrad version document.

## 7.2.5.4. Example

### 7.2.5.4.1. Example Request

    $ curl -s http://example.com/ | jq
    {
      "%Schema": "urn:com.io7m.ventrad:1",
      "Protocols": [
        {
          "Id": "com.io7m.stonesignal.device",
          "VersionMajor": 1,
          "VersionMinor": 0,
          "Endpoint": "/1/0/",
          "Description": "Stonesignal 1.0 Device API"
        }
      ]
    }

## 7.2.6. Endpoint: /device-location-put

## 7.2.6.1. Description

1
The /device-location-put is used to submit a location update from a device.

## 7.2.6.2. Request Type

1
The endpoint expects requests of the following type:

### 7.2.6.2.2. Request Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "type" : "object",
      "properties" : {
        "ACC" : {
          "type" : "number",
          "format" : "double",
          "description" : "The estimated horizontal accuracy radius in meters of this location."
        },
        "ALT" : {
          "type" : "number",
          "format" : "double",
          "description" : "The altitude of this location in meters above the WGS84 reference ellipsoid."
        },
        "BE" : {
          "type" : "number",
          "format" : "double",
          "description" : "The bearing at the time of this location in degrees. "
        },
        "BEACC" : {
          "type" : "number",
          "format" : "double",
          "description" : "The estimated bearing accuracy in degrees of this location."
        },
        "LAT" : {
          "type" : "number",
          "format" : "double",
          "description" : "The latitude in degrees."
        },
        "LONG" : {
          "type" : "number",
          "format" : "double",
          "description" : "The longitude in degrees."
        },
        "MSLALT" : {
          "type" : "number",
          "format" : "double",
          "description" : "The Mean Sea Level altitude of this location in meters."
        },
        "MSLALTACC" : {
          "type" : "number",
          "format" : "double",
          "description" : "The estimated Mean Sea Level altitude accuracy in meters."
        },
        "SP" : {
          "type" : "number",
          "format" : "double",
          "description" : "The speed at the time of this location in meters per second."
        },
        "SPACC" : {
          "type" : "number",
          "format" : "double",
          "description" : "The estimated speed accuracy in meters per second of this location."
        }
      }
    }

## 7.2.6.3. Response Type

1
The endpoint responds with an empty JSON object.

## 7.2.6.4. Example

### 7.2.6.4.1. Example

    $ cat data.json
    {
      "ACC": 1.0,
      "ALT": 32.0,
      ...

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 02210D83680AC0F4A50C47F51DCCE35610DE59717623A0D9408067279A63D511' \
      http://example.com/1/0/device-location-put
    {}

7.1. Admin API 1.0
Previous
7. API Access
Up
7.3. Data API 1.0
Next
io7m | single-page | multi-page | epub | Stonesignal User Manual 1.0.0-beta0001