Introduction to Spectera API

This introduction shall assist as a starting point for integrators to be able to integrate and connect the Spectera system with their 3rd-party client applications.

Understand the Spectera system

We have a couple of documents and videos on YouTube available, which might help getting familiar with the system behavior and setup of Spectera compared to todays known single carrier systems.

The communication between a 3rd-party client and the Spectera system will always be established via the Spectera Base Station network interface only. All other system components, like Antennas (DAD) or Mobile Devices (SEK), are aggregated dynamically via the API of the Base Station.

Understand the Sennheiser Sound Control (SSCv2)

A general introduction to our SSC protocol and the usage is provided on this website. Spectera does support Sennheiser Sound Control Protocol v2 (v2.3), with a high security standard, only.

Spectera Security Guide

A general introduction to all the security features of the Spectera system is documented in the Spectera Security Guide. This guide also explains in detail how to uses the device authentication incl. reset of device password.

CAUTION

Spectera API supports encrypted HTTPS communication on port 443 only. HTTP requests on default port 80 or port 443 will be rejected.

Authentication

It is mandatory to authenticate on the device with each HTTPS request.

CAUTION

Since the 3rd-party "API" access level is not implemented yet on Spectera, you have to use the existing access level used by our Sennheiser applications and NOT the "API" access level mentioned inside the general SSCv2 documentation.

  • Using HTTP basic authentication

  • Username: controlSennheiser

  • Password: configured using Sennheiser LinkDesk or WebUI

Brute-force prevention

Spectera Base Station has implemented a prevention mechanism making brute-force attacks on network interfaces impracticable. This ensures that whenever a client with a dedicated IP address tries to access a resource with wrong/invalid credentials repeatedly, this client with the dedicated IP address is blocked for a given time. The device does not keep the state for brute-force prevention across reboots.

Understand the Spectera API

This website publishes a YAML file with the OpenAPI specification of the Spectera API with all ressources accessable by the "API" access level.

Interface Versioning

At Sennheiser we follow a policy for versioning of the API. Here an abstract:

Introduction

Devices with an SSCv2 interface can be controlled and managed by clients over a REST-API. The functionality of the devices evolves over the time with new versions of the API, which add new features and modifies existing behavior.

This policy shall provide some rules and guidelines, how the versioning of an SSCv2 REST-API shall be treated.

Brief outline on Semantic Versioning

This document refers to Semantic Versioning Specification. Here an adapted short summary from the specification.

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes

  • MINOR version when you add functionality in a backward compatible manner

  • PATCH version when you make backward compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the MINOR version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. e.g. 1.0-alpha

Source: semver.org

Technical contract

Public SSCv2 Interface Version (client readable)

The SSCv2 Specification already defines a path and schema, that a client system is able to to retrieve the version information from the SCCv2 API of a device. This includes the protocol version and the schema version of the API.

/api/ssc/version:
  get:
    summary: Get the versions relevant for SSCv2 implemented
    description: An SSCv2 Command to retrieve the SSCv2 protocol and schema versions implemented in the SSCv2 Server
version:
    type: object
    properties:
        protocol:
            type: string
            example: "2.3"
            description: The version of SSC protocol.
        schema:
            type: string
            example: "17.0"
            description: This is the schema version of the API of the device. Semantic versioning must be used. So additional paths or properties will increase the minor number while breaking changes increase the integer part before the decimal point.

The schema version MUST follow the Semantic Versioning Specification.

CAUTION

  • For protocol and schema versions use only the MAJOR.MINOR parts of the version string and do not use the PATCH part nor any other additional label as prefix or suffix.

  • Both properties must be machine-readable and interpretable as numbers in order to perform numerical comparisons. The PATCH level is used if only the documentation of the YAML file has changed, e.g. the "description" property, which has no effect on the data transferred at the interface. Therefore, a client does not need to receive this information.

OpenAPI Specification Version

For the definition and documentation of an SSCv2 REST-API we are using OpenAPI Specification which already defines objects including the version information for the OpenAPI Specification being used and the version of the YAML file itself.

openapi: 3.1.0
info:
  title: SPECTERA API
  version: v17.0.1

Breaking Changes, Deprecated and Preliminary Features

CAUTION

Upcoming API versions may introduce breaking changes (reflected by the Major number of the API version string).

Sennheiser is trying to avoid breaking changes with new API versions as long as possible. Over the time we might need to refactor or improve functionality at the API. If we are going to change or even remove API functionality, we will give a grace period by deprecating the functionality officially. After an announced sunset date the deprecated functionality will be removed with a new API version.

In the OpenAPI specification the affected object will be marked with the deprecated property.

Connected:
  type: boolean
  description: |
    **DEPRECATED**: This property is going to be removed with the next major version of the API 
    - Use the `state` property with values "Connected" and "Disconnected" instead.
    - The value is "true" if the state equals "Connected" or "Updating", otherwise the value is "false".
  deprecated: true

Similarly it is about new functionality, which get's introduced by new API versions. Sometimes the functionality is not fully implemented or tested yet, but is already visible at the API. Such affected object will be just marked within the description property and will be mentioned in the release notes.

Sleep:
  type: boolean
  description: |
    **PRELIMINARY**: The Sleep Mode is a preliminary feature. The functionality is not fully implemented yet and the behavior may change in future versions of the API.