Introduction

WASP (Web AudioScience Protocol) is an HTTP based control protocol for AudioScience devices targeting both simple fire-and-forget clients and interactive UIs.

Simple clients

Simple clients are characterised by not keeping track of the device state between subsequent requests. A simple client usually has short lived sessions and is not interactive. A typical example would be a script launched once in a while which connects to the device to retrieve or update settings. A simple client could store information about the device to speed up certain operations but if it chooses to do so it must use the mechanism provided by the protocol to make sure cached information is up to date when re-connecting to the device at a later stage.

Interactive UIs

Interactive UIs are characterised by tracking a subset of a device’s state on the client. These clients usually have long lived sessions. A typical example can be a web based or native controller application.

Overview

At the highest level of abstraction a WASP device publishes two types of documents:

  1. A machine readable specifications in OpenAPI format with details about the API endpoints available on the device and schemas restricting acceptable values for properties in WASP objects.

  2. A number of WASP object instances that can be queried and updated.

Properties in WASP objects represent either protocol related information or state information and settings of the device. Property names starting with an underscore _ character are generally protocol related and do not represent device settings and state. For instance any WASP object will have an _id property identifying it for the purpose of lookup and a ctrl:trim_level object will have a level property controlling the full scale voltage of the analog input or output associated with the object.

Protocol description

WASP is a set of conventions and restrictions on HTTP 1.1 request and responses specified in the following sections.

HTTP URLs prefix

All URL destinations for WASP requests start with the /wasp/r1 prefix.

HTTP URLs endpoints

Endpoint paths are concatenated to the URL prefix. The following endpoints are available:

Endpoint path Summary Supported HTTP method

/device/info

Retrieve top level device information for this device.

GET

/device/ping

Check if the device is reachable and responsive.

GET

/objects

Enumerate objects

GET

/objects/{id}

Retrive or update object {id}

GET, PATCH

/objects/{id}/{prop}

Retrive or update property {prop} of object {id}

GET, PATCH

/spec/oas

Retrieve machine readable Open API Specification for this device.

GET

HTTP methods

WASP supports GET and PATCH HTTP methods respectively mapped to Retrieve and Update CRUD operations on WASP objects and properties.

HTTP statuses

HTTP statuses used by WASP retain their meaning as specified in the latest revision of the HTTP 1.1 protocol. Some statuses are mentioned here to clarify their meaning in the context of WASP transactions.

  • 200 : The request completed successfully and its side-effect applied.

  • 202 : The request was accepted for execution and is in progress. Its side-effect may not be applied yet by the time this status is received.

HTTP headers

A WASP server supports a number of standard and extension HTTP headers. Unsupported headers are ignored.

Content-Type

WASP currently recognizes only Content-Type: application/json.

X-HTTP-Method-Override

A client missing support for HTTP methods other than GET can include X-HTTP-Method-Override: METHOD in its request to work around the lack of support.

Connection

WASP uses the Connection header in its responses to inform the client if the connection should be closed or kept alive. A missing Connection header means Connection: keep-alive as specified by HTTP 1.1.

Sessions

A WASP session can encompass multiple HTTP connections during its life cycle. A new WASP session starts every time a WASP request is made to a server and either one of the following statement is true:

  • The server doesn’t recognise the session cookie carried by the request.

  • No session cookie is included with the request.

In case the request results in a new session the server shall include the new session cookie within its reply to the client.

The client shall always include the session cookie within each request and can detect when the session is invalidated by the server by comparing the value of the session cookie included in responses from the server. When the session cookie included with the response differs from the current cookie held by the client the former becomes the new session cookie and the client must assume all session bound state must be revalidated.

Client side state

WASP object space

A WASP device publishes a list of objects for clients to retrieve. Clients can retrieve all objects from a single object list with a single request or (not implemented yet!) request a subset of object filtering based on property values using URL query syntax. By default all properties of objects are included in the response but (not implemented yet!) properties included in the response can be restricted by [TBD].

Objects can also be retrieved one by one using their ID and updated one by one by including a set of property: new_value mappings as content of a PATCH request.

Common object properties

All objects published by WASP share a common set of properties shown in the following table.

Property name Type Description

_id

number

Numeric Object ID. Index of this object in the objects array.

_parent_id

number

Numeric Object ID. Index of this object’s parent in the objects array.

_schema

string

Schema ID string. The schema ID identifies the schema type used to validate an object. The ID is only valid for the duration of the session.

_type

string

Object type ID string. The object type ID identifies the API type associated with the object.

For instance a device:info object will be received as follows:

{
    "_id": 0,
    "_parent_id": null,
    "_schema": "_DeviceInfo",
    "_type": "device:info",
    "device_name": "Iyo Dante 32.32M",
    "label": "",
    "location": "Room 5",
    "main_hw_component_objid": 8,
    "main_sw_component_objid": 5,
    "status": "ok"
}

WASP object types

WASP identifies object types using the _type property of each object.

WASP defines the following object types and their set of properties.