io7m | single-page | multi-page | epub | Stonesignal User Manual 1.0.0-beta0001
7.2. Device API 1.0
Previous
7. API Access
Up
8. Security
Next

# 7.3. Data API 1.0

- 7.3.1. Overview
- 7.3.2. Formats
- 7.3.3. Authentication
- 7.3.4. Errors
- 7.3.5. Endpoint: /
  - 7.3.5.1. Description
  - 7.3.5.2. Request Type
  - 7.3.5.3. Response Type
  - 7.3.5.4. Example
- 7.3.6. Endpoint: /devices
  - 7.3.6.1. Description
  - 7.3.6.2. Request Type
  - 7.3.6.3. Response Type
  - 7.3.6.4. Example
- 7.3.7. Endpoint: /device-get-by-id
  - 7.3.7.1. Description
  - 7.3.7.2. Request Type
  - 7.3.7.3. Response Type
  - 7.3.7.4. Example
- 7.3.8. Endpoint: /device-locations
  - 7.3.8.1. Description
  - 7.3.8.2. Request Type
  - 7.3.8.3. Response Type
  - 7.3.8.4. Example
- 7.3.9. Endpoint: /device-locations-history
  - 7.3.9.1. Description
  - 7.3.9.2. Request Type
  - 7.3.9.3. Response Type
  - 7.3.9.4. Example

## 7.3.1. Overview

1
The data API is the API used to retrieve location data from the server. The data API is considered to be unprivileged, and therefore will not return any secrets such as device keys.
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.3.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.3.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.3.3. Authentication

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

### 7.3.3.3. Example

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 6890BF0E202343407CAF3FF100A118BDBB1BECABE343F3480E9A3DB0D9C889DC' \
      http://example.com/1/0/device-get-by-id

## 7.3.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.3.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.3.4.4. Error Schema

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

## 7.3.5. Endpoint: /

## 7.3.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-get-by-id endpoint would be reachable at /1/0/device-get-by-id.

## 7.3.5.2. Request Type

1
The endpoint ignores any request data.

## 7.3.5.3. Response Type

1
The endpoint responds with a ventrad version document.

## 7.3.5.4. Example

### 7.3.5.4.1. Example Request

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

## 7.3.6. Endpoint: /devices

## 7.3.6.1. Description

1
The /devices endpoint retrieves the set of defined devices.

## 7.3.6.2. Request Type

1
The endpoint expects requests of the following type:

### 7.3.6.2.2. Request Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "type" : "object"
    }

## 7.3.6.3. Response Type

1
The endpoint responds with objects of the following type:

### 7.3.6.3.2. Response Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "$defs" : {
        "Map(UUID,String)" : {
          "type" : "object"
        }
      },
      "type" : "object",
      "properties" : {
        "Devices" : {
          "$ref" : "#/$defs/Map(UUID,String)",
          "description" : "The devices by ID."
        }
      },
      "required" : [ "Devices" ]
    }

## 7.3.6.4. Example

### 7.3.6.4.1. Example

    $ cat data.json
    {}

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 6890BF0E202343407CAF3FF100A118BDBB1BECABE343F3480E9A3DB0D9C889DC' \
      http://example.com/1/0/devices
    {
      "Devices": {
        "f4f3bdce-fb35-4158-b122-4d7c861c1b18": "Fake",
        "70c49b44-f315-4d21-a1ab-60321fdc4bb6": "Fake",
        "f057fc17-07ef-4b89-8aa1-004eb992a364": "Fake"
      }
    }

## 7.3.7. Endpoint: /device-get-by-id

## 7.3.7.1. Description

1
The /device-get-by-id endpoint is used to retrieve the definition of a device by its ID.

## 7.3.7.2. Request Type

1
The endpoint expects requests of the following type:

### 7.3.7.2.2. Request Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "type" : "object",
      "properties" : {
        "DeviceID" : {
          "type" : "string",
          "format" : "uuid",
          "description" : "The device ID."
        }
      },
      "required" : [ "DeviceID" ]
    }

## 7.3.7.3. Response Type

1
The endpoint responds with objects of the following type:

### 7.3.7.3.2. Response Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "$defs" : {
        "Map(String,String)" : {
          "type" : "object"
        },
        "St1DataDevice" : {
          "type" : "object",
          "properties" : {
            "DeviceID" : {
              "type" : "string",
              "format" : "uuid",
              "description" : "The device ID."
            },
            "Metadata" : {
              "$ref" : "#/$defs/Map(String,String)",
              "description" : "The device metadata."
            },
            "Name" : {
              "type" : "string",
              "description" : "The device name."
            }
          },
          "required" : [ "DeviceID", "Metadata", "Name" ]
        },
        "St1DataDevice-nullable" : {
          "anyOf" : [ {
            "type" : "null"
          }, {
            "$ref" : "#/$defs/St1DataDevice"
          } ]
        }
      },
      "type" : "object",
      "properties" : {
        "Device" : {
          "$ref" : "#/$defs/St1DataDevice-nullable",
          "description" : "The device."
        }
      }
    }

## 7.3.7.4. Example

### 7.3.7.4.1. Example

    $ cat data.json
    {
      "DeviceID": "f4f3bdce-fb35-4158-b122-4d7c861c1b18"
    }

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 6890BF0E202343407CAF3FF100A118BDBB1BECABE343F3480E9A3DB0D9C889DC' \
      http://example.com/1/0/device-get-by-id
    {
      "Device": {
        "DeviceID": "f4f3bdce-fb35-4158-b122-4d7c861c1b18",
        "Name": "Fake",
        "Metadata": {}
      }
    }

## 7.3.8. Endpoint: /device-locations

## 7.3.8.1. Description

1
The /device-locations endpoint is used to retrieve the most recent location of all devices.

## 7.3.8.2. Request Type

1
The endpoint expects requests of the following type:

### 7.3.8.2.2. Request Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "type" : "object"
    }

## 7.3.8.3. Response Type

1
The endpoint responds with objects of the following type:

### 7.3.8.3.2. Response Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "$defs" : {
        "Map(UUID,St1DataLocation)" : {
          "type" : "object"
        }
      },
      "type" : "object",
      "properties" : {
        "Locations" : {
          "$ref" : "#/$defs/Map(UUID,St1DataLocation)",
          "description" : "The device locations by ID."
        }
      },
      "required" : [ "Locations" ]
    }

## 7.3.8.4. Example

### 7.3.8.4.1. Example

    $ cat data.json
    {}

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 6890BF0E202343407CAF3FF100A118BDBB1BECABE343F3480E9A3DB0D9C889DC' \
      http://example.com/1/0/device-locations
    {
      "Locations": {
        "f4f3bdce-fb35-4158-b122-4d7c861c1b18": {
          "ID": 3,
          "Time": "2025-04-13T13:27:47.056167Z",
          "Accuracy": 0.0,
          "Altitude": 0.0,
          "Bearing": 0.0,
          "BearingAccuracy": 0.0,
          "Latitude": 0.0,
          "Longitude": 0.0,
          "MSLAltitude": 0.0,
          "MSLAltitudeAccuracy": 0.0,
          "Speed": 0.0,
          "SpeedAccuracy": 0.0
        }
      }
    }

## 7.3.9. Endpoint: /device-locations-history

## 7.3.9.1. Description

1
The /device-locations-history endpoint is used to retrieve a list of locations for a specific device at some given point in the past.

## 7.3.9.2. Request Type

1
The endpoint expects requests of the following type:

### 7.3.9.2.2. Request Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "type" : "object",
      "properties" : {
        "Count" : {
          "type" : "integer",
          "format" : "int32",
          "description" : "The maximum number of events to return."
        },
        "DeviceID" : {
          "type" : "string",
          "format" : "uuid",
          "description" : "The device ID."
        },
        "TimeStart" : {
          "type" : "string",
          "format" : "date-time",
          "description" : "The start time."
        }
      },
      "required" : [ "Count", "DeviceID", "TimeStart" ]
    }

## 7.3.9.3. Response Type

1
The endpoint responds with objects of the following type:

### 7.3.9.3.2. Response Schema

    {
      "$schema" : "https://json-schema.org/draft/2020-12/schema",
      "$defs" : {
        "St1DataLocation" : {
          "type" : "object",
          "properties" : {
            "Accuracy" : {
              "type" : "number",
              "format" : "double",
              "description" : "The estimated horizontal accuracy radius in meters of this location."
            },
            "Altitude" : {
              "type" : "number",
              "format" : "double",
              "description" : "The altitude of this location in meters above the WGS84 reference ellipsoid."
            },
            "Bearing" : {
              "type" : "number",
              "format" : "double",
              "description" : "The bearing at the time of this location in degrees. "
            },
            "BearingAccuracy" : {
              "type" : "number",
              "format" : "double",
              "description" : "The estimated bearing accuracy in degrees of this location."
            },
            "ID" : {
              "type" : "integer",
              "format" : "int64",
              "description" : "The location ID."
            },
            "Latitude" : {
              "type" : "number",
              "format" : "double",
              "description" : "The latitude in degrees."
            },
            "Longitude" : {
              "type" : "number",
              "format" : "double",
              "description" : "The longitude in degrees."
            },
            "MSLAltitude" : {
              "type" : "number",
              "format" : "double",
              "description" : "The Mean Sea Level altitude of this location in meters."
            },
            "MSLAltitudeAccuracy" : {
              "type" : "number",
              "format" : "double",
              "description" : "The estimated Mean Sea Level altitude accuracy in meters."
            },
            "Speed" : {
              "type" : "number",
              "format" : "double",
              "description" : "The speed at the time of this location in meters per second."
            },
            "SpeedAccuracy" : {
              "type" : "number",
              "format" : "double",
              "description" : "The estimated speed accuracy in meters per second of this location."
            },
            "Time" : {
              "type" : "string",
              "format" : "date-time",
              "description" : "The time the update was received."
            }
          },
          "required" : [ "ID", "Time" ]
        }
      },
      "type" : "object",
      "properties" : {
        "Locations" : {
          "description" : "The device locations.",
          "type" : "array",
          "items" : {
            "$ref" : "#/$defs/St1DataLocation"
          }
        }
      },
      "required" : [ "Locations" ]
    }

## 7.3.9.4. Example

### 7.3.9.4.1. Example

    $ cat data.json
    {
      "DeviceID": "f4f3bdce-fb35-4158-b122-4d7c861c1b18",
      "TimeStart": "2025-04-13T00:00:00+00:00",
      "Count": 1000
    }

    $ curl \
      --data-binary @data.json \
      --header 'Content-Type: application/stonesignal+json' \
      --header 'Authorization: Bearer 6890BF0E202343407CAF3FF100A118BDBB1BECABE343F3480E9A3DB0D9C889DC' \
      http://example.com/1/0/device-location-history
    {
      "Locations": [
        {
          "ID": 1,
          "Time": "2025-04-13T11:58:41.266913Z",
          "Accuracy": 0.0,
          "Altitude": 0.0,
          "Bearing": 0.0,
          "BearingAccuracy": 0.0,
          "Latitude": 0.0,
          "Longitude": 0.0,
          "MSLAltitude": 0.0,
          "MSLAltitudeAccuracy": 0.0,
          "Speed": 0.0,
          "SpeedAccuracy": 0.0
        },
        {
          "ID": 2,
          "Time": "2025-04-13T13:27:42.179066Z",
          "Accuracy": 0.0,
          "Altitude": 0.0,
          "Bearing": 0.0,
          "BearingAccuracy": 0.0,
          "Latitude": 0.0,
          "Longitude": 0.0,
          "MSLAltitude": 0.0,
          "MSLAltitudeAccuracy": 0.0,
          "Speed": 0.0,
          "SpeedAccuracy": 0.0
        },
        {
          "ID": 3,
          "Time": "2025-04-13T13:27:47.056167Z",
          "Accuracy": 0.0,
          "Altitude": 0.0,
          "Bearing": 0.0,
          "BearingAccuracy": 0.0,
          "Latitude": 0.0,
          "Longitude": 0.0,
          "MSLAltitude": 0.0,
          "MSLAltitudeAccuracy": 0.0,
          "Speed": 0.0,
          "SpeedAccuracy": 0.0
        }
      ]
    }

7.2. Device API 1.0
Previous
7. API Access
Up
8. Security
Next
io7m | single-page | multi-page | epub | Stonesignal User Manual 1.0.0-beta0001