AVM: API

Summary

The AdderView Matrix (AVM) provides a RESTful API defined using the OpenAPI specification, enabling the control and configuration of Receivers and Transmitters. Additionally, it implements an Events API—a socket-based, event-driven interface for listening to real-time changes. This page covers the OpenAPI; please refer to the Events API documentation for more information.

This is not intended to be an exhaustive guide on using APIs. It is assumed that readers are already familiar with REST APIs and the various mechanisms through which they can be accessed.

Resources

The following API resources are available for download:

YAML File:

• Download OpenAPI - RESTful API control

Postman:

• Download Workspace - A pre-built RESTFul API Workspace for testing

  

What are ETags

The API uses ETags (short for Entity Tag) to ensure that you have the correct status of a device before updating or changing any settings on the Receiver. When requesting a resource, such as a list of Presets, the server sends an ETag header in the response. The ETag is unique to each specific request—for example, requesting a list of presets or devices will return different ETags. To make a change, the ETag must be included in the POST or PATCH request. If the status changes between the initial request and the submission of the change request, the request will be rejected.

For example, when requesting a list of presets, you would use GET https://{RX_IP}/api/presets. The header response will contain the ETag:

Once you have the ETag, you will need to store it and add it to the headers as an If-Match header of the POST or PATCH request:

Tokens

Before you can make any changes to the system, you must log in and retrieve a JWT token. To retrieve a token, you must provide a valid password. By default, this password is set to 'password', but it can be changed on each device. Currently, only one user is supported. A token is valid for 24-hours.

Use POST https://{RX_IP}/users/login/1 with the following text in the body of the request. Replace the password if you have changed the default, which is empty.

The JSON response will give you AuthToken that you need to store.

Sources and Sinks

Sources and Sinks correspond to the physical connection ports, ie, Video, Audio, USB, and Serial ports. Sources are found on the Transmitter and Sinks are found on the Receiver. Getting the Source and Sink information will give you Port ID's required for setting presets, as well as give you information about the capability of each port.

Control

This section will cover changing channels on an AVM Receiver. The how-to instructions assume you have experience with HTTP-based APIs.

How to Get a List of Presets

To get a list of the current Presets and their Id required to change channels you need to use GET https://{RX_IP}/api/presets..

How to Change Preset

1. Make sure you have a Token. See the Tokens section.
2. Get the current selected preset ETag:
   • Use GET https://{RX_IP}/api/presets/selected
   • This will return a JSON with the current preset Id and the ETag in the header
     
     Response Header
     
     Date: Wed, 28 Aug 2024 16:26:56 GMT
     Content-Type: application/json; charset=utf-8
     Access-Control-Allow-Origin: *
     ETag: "75541d8d1ebac03231d87db3e917c742"
     Access-Control-Expose-Headers: ETag
     Content-Length: 36
     
     JSON
     
     {
       "presetId": 1,
       "accessMode": "viewOnly"
     }
     
     
   • In this example, Preset Id 1 is currently selected.
     
     
3. Using the ETag, you can now change the preset.
   • Use PATCH https//{RX_ID}/api/presets/selected
     Add your Authorization Token and ETag to the headers:
     
     Authorization: {Token}
     If-Match: "75541d8d1ebac03231d87db3e917c742"
     
     In the JSON body, set the Preset Id and the Mode
     
     {
         "presetId: {ID},
         "mode":  {mode}
     }