swagger: '2.0' info: version: '1.05' title: XDIP PUBLIC REST API description: | Adder Technology XDIP Public REST API. The API gives the user the ability to control the channel a receiver is connected to, obtain all the neccessary information relating to the connected channel and gain an authorization access token required to switch channels, given knowledge of the node's 'Access' password. It does not give the user the ability to change the channel configuration or any other part of the node's configuration, in order to do this a user must log in to the OSD directly and access the admin screen - which will require knowledge of the 'Admin' password. This API requires the use of TLS v1.2. schemes: - https basePath: /api consumes: - application/json - multipart/form-data produces: - application/json paths: '/channels': get: tags: - Channels summary: Return a list of channels configured in the system. For future use, each channel has a list of nodes. Only one node is presently returned in this list. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string responses: '200': description: OK. headers: ETag: type: string description: ETag for the data response. schema: type: array description: Number of channels. items: type: object properties: id: description: The channel Id, which also specifies the hot-key shortcut and position on the channel selection OSD. type: integer format: int32 nodes: description: List of nodes that make up this channel. type: array items: type: object properties: nodeUuid: description: The unique identifier for the node associated with the channel. type: string maxLength: 36 '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '500': description: Operation Failed. '/channels/{id}': get: tags: - Channels summary: Get details of a single channel. For future use, a channel has a list of nodes. Only one node is presently returned in this list. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string - in: path name: id description: Channel Id. type: string required: true responses: '200': description: OK. headers: ETag: type: string description: ETag for the data response. schema: type: object properties: id: description: The channel Id, which also specifies the hot-key shortcut and position on the channel selection OSD. type: integer format: int32 nodes: description: List of nodes that make up this channel. type: array items: type: object properties: nodeUuid: description: The unique identifier for the node that is associated with the channel. type: string maxLength: 36 '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '404': description: Channel Id Not In Supported Range. '500': description: Operation Failed. '/channels/connected': get: tags: - Channels summary: Get the channel this node is currently connected too. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string responses: '200': description: OK. headers: ETag: type: string description: ETag for the data response. schema: type: object properties: id: description: The channel Id, which also specifies the hot-key shortcut and position on the channel selection OSD. An id of 0x7fffffff indicates that the node is currently not connected to a channel. type: integer format: int32 '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '500': description: Operation Failed. '/channels/{id}/switch': post: tags: - Channels summary: Switch node to the specified channel. parameters: - in: path name: id description: Channel Id. An id of 0x7fffffff will cause the receiver to disconnect from the current channel. type: string required: true - in: header name: Authorization description: Access / Admin JSON Web Token (JWT). Format 'Bearer JWT' required: true type: string responses: '204': description: Successful Operation (No Content). '401': description: Unauthorised. Invalid Access Credentials Provided. '404': description: Channel Id Not In Supported Range. '500': description: Operation Failed. '/channels/maximumAllowed': get: tags: - Channels summary: Get the maximum number of channels supported by this node. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string responses: '200': description: OK. headers: ETag: type: string description: ETag for the data response. schema: type: object properties: count: description: The maximum number of channels supported by this node. type: integer format: int32 readOnly: true '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '500': description: Operation Failed. '/channels/status': get: tags: - Channels summary: Get the status for the currently selected channel. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string responses: '200': description: Ok. headers: ETag: type: string description: ETag for the data response. schema: type: object properties: summary: description: | The summarised status of the connections that are associated with the current channel. This should be used to determine if the current channel is operational, while the other elements can be used to ascertain why the channel may not be operational. * disconnected - indicates that no channel is currently selected. * connecting - indicates that a channel switch is currently in progress. * connected - indicates that the channel is working. * failedAuthorisation - indicates that at least one of the connections failed it's authentication with the peer node. * failedResolution - indicates that the video resolution for the channel cannot be supported by this node. * noVideo - indicates that there is no video data being received from the channel. type: string enum: - disconnected - connecting - connected - failedAuthorisation - failedResolution - noVideo connections: type: array description: The connections that are associated with the channel. items: type: object properties: id: description: Identifies the type of the connection this entry is for. type: string state: description: | The state of this connection. * disconnected - indicates that no connection exists. * connecting - indicates that the connection is trying to be established. * connected - indicates that the connection is established. type: string enum: - disconnected - connecting - connected status: description: | The status of this connection. * ok - will indicate that the connection was successfully established. * unknown - will indicate that the connection attempt has not yet completed and further requests should be performed until this value changes. * badAuthorisation - will indicate that the Access credentials needed for the channel connection were incorrect. * incompatibleResolution - will indicate that the video resolution for the channel is not supported by this node. * noInput - will indicate that no input data is being received from the channel. type: string enum: - unknown - ok - badAuthorisation - incompatibleResolution - noInput '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '500': description: Operation Failed. '/nodes/{uuid}': get: tags: - Nodes summary: Get details of a single node. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string - in: path name: uuid description: The node's unique identifier (or 'self' for local node). type: string required: true responses: '200': description: OK. headers: ETag: type: string description: ETag for the data response. schema: type: object properties: uuid: description: Unique node Id identifying this node. type: string maxLength: 36 name: description: Friendly name for this node. type: string maxLength: 31 description: description: Node description. type: string maxLength: 63 type: $ref: '#/definitions/nodeType' active: description: Set true when node is powered and connected to the network. type: boolean serialNumber: description: The manufacturing serial number of this node. type: string readOnly: true macAddress: description: The MAC address of this node. type: string readOnly: true '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '404': description: UUID Not Found. '500': description: Operation Failed. '/nodes/selected': get: tags: - Nodes summary: Returns a list and details of the configured Channel nodes. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string required: true responses: '200': description: OK. headers: ETag: type: string description: ETag for the data response. schema: type: array description: List of selected nodes. items: type: object properties: uuid: description: Unique node Id identifying this node. type: string maxLength: 36 name: description: Friendly name for this node. type: string maxLength: 31 description: description: Node description. type: string maxLength: 63 type: $ref: '#/definitions/nodeType' active: description: Set true when node is powered and connected to the network. type: boolean serialNumber: description: The manufacturing serial number of this node. type: string readOnly: true macAddress: description: The MAC address of this node. type: string readOnly: true '304': description: Not Modified. headers: ETag: type: string description: ETag for the data response. '500': description: Operation Failed. '/nodes/self/access': post: tags: - Access summary: Obtain an Access token JSON Web Token (JWT) using the provided password. parameters: - in: path name: uuid description: The node's unique identifier. type: string required: true - in: body name: authData description: Password attributes. required: true schema: type: object required: - accessPassword properties: accessPassword: description: The Access password for the node. type: string maxLength: 31 responses: '200': description: OK. schema: type: object properties: accessToken: description: Access token with the requested privileges. type: string '400': description: Invalid Content (Schema). '401': description: Unauthorised. '404': description: UUID Not Found. '500': description: Operation Failed. '/localComputer': get: tags: - LocalComputer summary: Get information relating to the computer that is connected to this node. parameters: - in: header name: If-None-Match description: ETag for the client's copy of the data response. type: string responses: '200': description: OK. headers: ETag: description: ETag for the data response. type: string schema: type: object properties: name: description: The friendly name associated with the local computer. type: string maxLength: 31 description: description: The description associated with the local computer. type: string maxLength: 63 '304': description: Not Modified. headers: ETag: description: ETag for the data response. type: string '500': description: Operation Failed. definitions: nodeType: description: Types of nodes. type: string enum: - transmitter - receiver - startOfLife