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

# 7.1. Admin API 1.0

- 7.1.1. Overview
- 7.1.2. Formats
- 7.1.3. Authentication
- 7.1.4. Errors
- 7.1.5. Endpoint: /
  - 7.1.5.1. Description
  - 7.1.5.2. Request Type
  - 7.1.5.3. Response Type
  - 7.1.5.4. Example
- 7.1.6. Endpoint: /device-get-by-id
  - 7.1.6.1. Description
  - 7.1.6.2. Request Type
  - 7.1.6.3. Response Type
  - 7.1.6.4. Example
- 7.1.7. Endpoint: /device-get-by-key
  - 7.1.7.1. Description
  - 7.1.7.2. Request Type
  - 7.1.7.3. Response Type
  - 7.1.7.4. Example
- 7.1.8. Endpoint: /device-put
  - 7.1.8.1. Description
  - 7.1.8.2. Request Type
  - 7.1.8.3. Response Type
  - 7.1.8.4. Example

## 7.1.1. Overview

1
The admin API is the API used to accept administrative commands.
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.1.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.1.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.1.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.1.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.1.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.1.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.1.4.4. Error Schema

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

## 7.1.5. Endpoint: /

## 7.1.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.1.5.2. Request Type

1
The endpoint ignores any request data.

## 7.1.5.3. Response Type

1
The endpoint responds with a ventrad version document.

## 7.1.5.4. Example

### 7.1.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.1.6. Endpoint: /device-get-by-id

## 7.1.6.1. Description

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

## 7.1.6.2. Request Type

1
The endpoint expects requests of the following type:

### 7.1.6.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.1.6.3. Response Type

1
The endpoint responds with objects of the following type:

### 7.1.6.3.2. Response Schema

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

## 7.1.6.4. Example

### 7.1.6.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",
        "DeviceKey": "0D00B8679D5CA37A731BBA2575AD259E9E0309517E16010A0ED55792E5C6D56D",
        "Name": "Fake",
        "Metadata": {}
      }
    }

## 7.1.7. Endpoint: /device-get-by-key

## 7.1.7.1. Description

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

## 7.1.7.2. Request Type

1
The endpoint expects requests of the following type:

### 7.1.7.2.2. Request Schema

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

## 7.1.7.3. Response Type

1
The endpoint responds with objects of the following type:

### 7.1.7.3.2. Response Schema

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

## 7.1.7.4. Example

### 7.1.7.4.1. Example

    $ cat data.json
    {
      "DeviceKey": "0D00B8679D5CA37A731BBA2575AD259E9E0309517E16010A0ED55792E5C6D56D"
    }

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

## 7.1.8. Endpoint: /device-put

## 7.1.8.1. Description

1
The /device-put endpoint is used to update or create the definition of a device.

## 7.1.8.2. Request Type

1
The endpoint expects requests of the following type:

### 7.1.8.2.2. Request Schema

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

## 7.1.8.3. Response Type

1
The endpoint responds with an empty object.

## 7.1.8.4. Example

### 7.1.8.4.1. Example

    $ cat data.json
    {
      "Device": {
        "DeviceID": "f057fc17-07ef-4b89-8aa1-004eb992a364",
        "DeviceKey": "ACCD3D5D5C3864083E371BD1E161C6071C3A847943CCCA6A833CECC1FA67D30C",
        "Name": "Fake",
        "Metadata": {
          "Manufacturer": "Bad Phones LLC"
        }
      }
    }

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

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