HTTP is based on the Request-Response-Pattern, meaning every answer from the server must be triggered by a request by the client. The response happens immediately. Although there are some approaches with delayed answer (e.g. the server sending a reply indicating it is not finished until the answer is ready), this still follows the Request-Response-Model. To allow for unsolicited messages after an initial subscription Server Sent Events (SSE) are specified. They define a mechanism for clients to tell the server they want to be able to receive asynchronous messages and for the server to send these to them without a dedicated request for each response.

Server Sent Events are developed as a living standard by the Web Hypertext Application Technology Working Group (WHATWG). It can be found at: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events

Case sensitivity is a contested topic. SSCv2 is following the standards it uses in this regard:

• The path component of an URI MUST be implemented case sensitive, as per RFC 3986, 6.2.2.1, "Case normalization". An SSCv2 schema still SHOULD avoid specifying paths which are ambiguous on case.
• As JSON specifies its strings to follow C conventions and nearly all JSON implementations are case sensitive, the JSON payload MUST be interpreted by SSCv2 Clients and SSCv2 Servers as case sensitive. An SSCv2 schema still SHOULD avoid specifying entities which are ambiguous on case.

The following optional parts of HTTP(S) have been made mandatory or are recommended for SSCv2:

• An SSCv2 Server MUST implement HTTPS (=encrypted connections)
• An SSCv2 Server MUST NOT allow HTTP (=unencrypted connections)
• An SSCv2 Server MUST implement HTTP/1.1
• An SSCv2 Server SHOULD implement persistent connections to limit the amount of new connections needed
• An SSCv2 Client SHOULD use persistent connections

Note for development: An SSCv2 Server MAY implement a development build allowing for HTTP (e.g. to help with debugging), but MUST ensure that HTTP is not possible in release versions.

The following optional parts of JSON have been made mandatory or are recommended for SSCv2:

• An SSCv2 Server MUST return all text-based entities as a JSON object. While JSON allows for singular values to be returned in a plain way, this is a newer addition to the JSON standard and might not be supported by all JSON libraries.

A Message is the protocol unit of transmission. There are two ways of message exchange:

• Synchronous: The client sends a request and the server immediately sends a response
• Asynchronous: The client subscribes for parameter changes and the server notifies the client on parameter changes via SSE.

An SSCv2 Message MUST be sent as a single closed JSON form describing a JSON object. This means that every SSCv2 Message is enclosed in a pair of curly brackets { }. There MUST NOT be more than one SSCv2 message per HTTP request.

By default, the SSCv2 Server SHOULD execute the SSCv2 Command immediately, i.e., as soon as possible after receipt of the message.

An SSCv2 Server MAY expose a representation of its current absolute device time. The optional SSCv2 Command /device/time MAY be used to query and optionally set the device time. SSCv2 does not provide a mechanism for clock synchronization; if an SSCv2 Server utilizes a mechanism like NTP or PTP to sync to the absolute time it MUST implement /device/time as read-only parameter. See also the description of this resource in General SSCv2 Address Schema.

If the SSCv2 Server expects the execution of a command to exceed 5 seconds it MUST immediately send an HTTP response with status code 102 - processing. When the command execution is finished the SSCv2 Server finalizes the request by sending the response containing the final result and appropriate status code (e.g. 200 - ok or corresponding error).

A resource MAY have an array of elementary data as entity. The array MAY be empty. The SSCv2 Command acting upon the resource MUST NOT switch between returning arrays and elementary data.

All the elements of the array MUST have the same elementary data type.

In previous version of this standard the access of array (special) ranges was required, this SHOULD NOT be used anymore.

An SSCv2 Session is defined by the association of a specific SSCv2 Client with an SSCv2 Server. The SSCv2 Server MUST keep state information specific to each SSCv2 Client (e.g., state relating to SSCv2 subscriptions, or authorization). The SSCv2 Server MUST couple the state to the SSCv2 Session. When the SSCv2 Session terminates, session state MUST be cleared (e.g., all SSCv2 subscriptions of the client are cancelled).

An SSCv2 Session begins with establishing the HTTPS connection from a specific SSCv2 Client to an SSCv2 Server.

The SSCv2 Session MUST last for the duration of the connection. The SSCv2 Session MUST be terminated when the connection is closed by either side.

The SSCv2 Server SHOULD keep state information that is explicitly specific to the SSCv2 Session in SSCv2 Addresses that are below /api/ssc/state, e.g., information about SSCv2 subscriptions (see also section SSCv2 subscriptions - /api/ssc/state/subscriptions). Additionally, SSCv2 Server state specific for an SSCv2 Session MAY affect the results of SSCv2 Commands (e.g. it might reject specific SSCv2 Commands if an SSCv2 Client lacks sufficient access permission).

The SSCv2 Server MUST NOT coalesce SSCv2 Sessions together based on authorization credentials. Multiple SSCv2 sessions per authorization credential MUST be the default.

If an SSCv2 Client wants to request the subscription status attached to a sessionUUID, it MUST use a GET request to /api/ssc/state/subscriptions using this sessionUUID. An SSCv2 Server MUST check that the permission of the SSCv2 Client requesting is adequate for requesting the subscription list associated with the sessionUUID. For example with an control user and an API user, the control user SHOULD be allowed to request the subscription list for any user, while the API user is only allowed to get lists created with the API user. The different users are specified in the "Specification for Authenticated Sennheiser Sound Control (SSC) Clients".

An SSCv2 Server MUST ensure that this subscription has been created by the same user as the user sending the request.

An SSCv2 Server MUST treat a non-existing sessionUUID as an error.

OpenAPI snippet

/api/ssc/state/subscriptions/{sessionUUID}:
  get:
    summary: Get the subscription list
    description: An SSCv2 Command to retrieve the list of subscriptions associated with the sessionUUID
    parameters:
        - in: path
          name: sessionUUID
          schema:
            type: string
          required: true
    responses:
      '200':
        description: Successful request
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: /api/device/site
      '401':
        description: Unauthorized since no user credentials are passed
      '403':
        description: User is not allowed to get subscription list for this sessionUUID
      '422':
        description: sessionUUID did not exist
      '500':
        description: SSCv2 Server encountered internal error

It is possible to either change the full set of resources of a subscription, or to add/remove resources from the currently subscribed set.

An SSCv2 Client can end a subscription either implicitly or explicitly.

• To end a subscription implicitly, the SSCv2 Client just closes the connection receiving the subscription data.
• To end a subscription explicitly, an SSCv2 Client uses the DELETE request method to the resource /api/ssc/state/subscriptions/{sessionUUID}. When using the explicit method, the SSCv2 Server MUST send a close-event to the subscription, before it closes the connection. The data sent in the close-event is the same as in the open-event.

The SSCv2 Server MUST terminate a subscription in these cases:

• the subscribed client cancels the subscription explicitly
• the SSCv2 Client closes the connection
• the transport layer of the SSCv2 connection signals a fatal communication error
• the password of the user used to create the subscription was changed

When a subscription is closed, an SSCv2 Server MUST remove the associated sessionUUID.

When a subscription is closed explicitly, the SSCv2 Server MUST ensure that this subscription has been created by the same user as the user sending the request.

An SSCv2 Server MUST ensure to only close the subscriptions created using the credentials whose password has been changed. An SSCv2 Server MUST close subscriptions regardless whether the password was actually changed or the already present password was set again.

OpenAPI snippet

/api/ssc/state/subscriptions/{sessionUUID}:
  delete:
    summary: End an existing subscription
    description: An SSCv2 Command to end the subscription associated with the sessionUUID
    parameters:
        - in: path
          name: sessionUUID
          schema:
            type: string
          required: true
    responses:
      '200':
        description: Successful request
      '401':
        description: Unauthorized since no user credentials are passed
      '403':
        description: User is not allowed to end subscription for this sessionUUID
      '422':
        description: sessionUUID did not exist
      '500':
        description: SSCv2 Server encountered internal error

The SSCv2 Client MAY request to subscribe to multiple resources in a single request by design.

The SSCv2 Server MUST treat all those subscription requests as one transaction. If the SSCv2 Server is not able to satisfy subscription to one of the resources it MUST send an error and refuse all resources. If there are already subscribed resources present, the previous subscribed state MUST remain unchanged.

When the SSCv2 Server refuses a request for a subscription or a set of subscriptions, it MUST return an object containing the resource which was not subscribeable and the reason for the error. The SSCv2 Server MUST stop processing a request for a set of subscriptions after encountering the first invalid subscription in the request. The following error codes MUST be used:

• 403 if subscribing to the resource is not allowed for the user
• 404 if the resource does not exist

A subscription notification is JSON object as Server Sent Event (SSE) data, using the resource triggering the notification as a key and the entities of the resource wrapped in a JSON object as value. An SSCv2 Server MAY combine notifications for multiple resources in one JSON object, if the update occurs at the same time. Since a newly created subscription of multiple addresses MUST report the values of the resources this MAY be combined into a bigger JSON object. If this combination of the different resources is not supported, all notifications MUST be send in the stream as individual JSON objects.

The following example shows the stream of a notification after a initial subscription and a later notification of the change of the name:

{
    "/api/device/site":  
  {
        "name": "MyDevice",
        "location": "Chemistry Building 5, Room 15",
        "site": "Left side near the big pillar"
    }
}
{
  "/api/device/site":  
  {
    "name": "MyRenamedDevice",
    "location": "Chemistry Building 5, Room 15",
    "site": "Left side near the big pillar"
    }
}

The address /api/device/site was subscribed, the initial values were reported. After some time the name was changed and the resulting update was sent as a second JSON object.

A read-only resource containing standard information about the device in question. The following entities are mandatory:

• product: Product identification, should be identical to the designation on the label on the product itself.
• serial: Unique product number, MUST be unique for this product.
• vendor: Vendor string, for Sennheiser-products it is „Sennheiser“.

OpenApi snippet:

/api/device/identity:
  get:
    summary: Get the device identity
    description: An SSCv2 Command to retrieve the device identity
    responses:
      '200':
        description: Successful request
        content:
          application/json:
            schema:
              type: object
              properties:
                product:
                  type: string
                  example: TeamConnect Ceiling 2
                hardwareRevision:
                  type: string
                  example: DVT
                serial:
                  type: string
                  example: AB12DEF345
                vendor:
                  type: string
                  example: Sennheiser electronic GmbH & Co. KG
                  enum:
                    - Sennheiser electronic GmbH & Co. KG
      '500':
        description: SSCv2 Server encountered internal error

User-changeable values helping the user to individualize the device and the most convenient way for the customer to identify the device. The resource MUST contain and allow for configuration the following entities:

• deviceName: User-settable persistent device name. This name should be the preferred, and most convenient way for the customer to identify devices. If the device has a display, this name SHOULD be displayed there, preferably in the network context; if it has a menu, this name SHOULD be configurable or be derived from /api/device/identity or/and and the location entity of this resource. This name is to be understood as device identification in a network environment.
• location: User-settable persistent installation location, like e.g. Chemistry Building 5, Room 15. Free-form string entity.
• position: User-settable persistent position in the installation location in case there are multiple devices at the installation location. Free-form string entity.

The maximum length of string entities CAN be decided by a device and MUST be communicated using the OpenAPI schema for the device.

OpenApi snippet:

/api/device/site:
  get:
    summary: Get the device site information
    description: An SSCv2 Command to retrieve the device site information
    responses:
      '200':
        description: Successful request
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: MyDevice
                location:
                  type: string
                  example: Chemistry Building 5, Room 15
                position:
                  type: string
                  example: Left side near the big pillar
      '401':
        description: Unauthorized since no user credentials are passed
      '403':
        description: User is not allowed to access this resource
      '500':
        description: SSCv2 Server encountered internal error
  put:
    summary: Write the device site information
    description: An SSCv2 Command to set the device site information
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              deviceName:
                type: string
                maximum: 60
                example: MyDevice
              location:
                type: string
                maximum: 240
                example: Chemistry Building 5, Room 15
              position:
                type: string
                maximum: 240
                example: Left side near the big pillar
    responses:
      '200':
        description: Successful operation
      '400':
        description: Bad Request
      '401':
        description: Unauthorized since no user credentials are passed
      '403':
        description: User is not allowed to access this resource
      '500':
        description: Internal Server Error

For Dynamic Resources subscriptions are handled in a special manner. A subscription to the the control resource will be recorded in the list of subscribed resources, but implicitly it is a subscription to all controlled subresources, currently existing and created later. A client will receive updates for all subresources and resources below them instead of changes of the control resource. An SSCv2 Server implementing subscriptions for Dynamic Resources adheres to the following rules:

• A subscription to a control resource MUST only record the subscription to the control resource in the list of subscribed resources
• On subscription to the control resource the SSCv2 Server MUST send an update for all existing subresources controlled by this control resource, as well as for all resources below the subresources
• If a client subscribes to a control resource and explicitly to a specific subresource or a resource below a subresource, the SSCv2 Server MUST treat this as two different subscriptions and send two updates for the same resource on update

The following example shows a pattern allowing for ordered creation, monitoring, updating and deletion of dynamic resources:

/api/device/dsp/modules/agc:
  get:
    summary: Returns list of instantiated AGC modules
    description: Returns list of instantiated AGC modules
    x-sennheiser-sscv2-resourcetype: [ "ControlResource" ]
    x-sennheiser-sscv2-subresource: "/api/device/dsp/modules/agc/{instanceId}"
    responses:
      '200':
        description: Successful request
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  instanceId:
                    type: string
                  value1:
                    type: string
                  value2:
                    type: string
                  value3:
                    type: string
      '403':
        description: Access permission not sufficient
  post:
    summary: Instantiate a new AGC module
    description: Instantiate a new AGC module
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              value1:
                type: string
              value2:
                type: string
              value3:
                type: string
    responses:
      '201':
        headers:
          Location:
            description: Location of the newly created resource
            schema:
              type: string
        description: Successful creation
      '403':
        description: Access permission not sufficient

/api/device/dsp/modules/agc/{instanceId}:
  parameters:
    - name: instanceId
      in: path
      description: Instance to update
      required: true
      schema:
        type: string
  get:
    summary: Return the currently configured values
    description: Return the currently configured values of the AGC module at instanceId
    responses:
      '200':
        description: Successful request
        content:
          application/json:
            schema:
              properties:
                value1:
                  type: string
                value2:
                  type: string
                value3:
                  type: string
      '403':
        description: Access permission not sufficient
  put:
    summary: Change AGC module at instanceId
    description: Change AGC module at instanceId
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              value1:
                type: string
              value2:
                type: string
              value3:
                type: string
    responses:
      '200':
        description: Successful request
      '403':
        description: Access permission not sufficient
  delete:
    summary: Delete and Deinstantiate the AGC module at instanceId
    responses:
      '200':
        description: Successful deletion
      '403':
        description: Access permission not sufficient

This resource is used to signal special resources, which have behavior exceeding normal REST semantics. The following resource types are specified:

• FastResource: A resource, which is expected to update frequently. This allows a consumer of the Api to shape the traffic by only subscribing to this resource, when working with the data.

• ControlResource: A resource, which is following the special semantics laid out in Dynamic Resources. Subscribing to this resource will not trigger subscription updates for the ControlResource, but updates for every subresource instead.

• RebootingResource: A resource, which will trigger a reboot on PUT/POST interaction.

The resource type vendor extensions MUST be used on specific operations.

Please Note, that prerelease versions of the 2.3 specification standardized usage of a tag "FastResource". Consumers of SSCv2 api specifications MUST treat a tag "FastResource" identically to the respective x-sennheiser-sscv2-resourcetype vendor extension, if they encounter it, while creators of SSCv2 api specifications MUST NOT use the tag FastResource for new specifications.

This vendor extension MUST only be used, when the resource is of the resource type ControlResource. It MUST contain the dynamic resource controlled by this control-resource and is used as a hint for code generation.