Loading...
 

XDIP: Using the API

Overview

The XDIP uses a RESTFul JSON JavaScript Object Notation) based API for simple channel control of a receiver.

A copy of the API in YAML form can be download from the link below:-
Download XDIP API

An example C# API class has been written and published on Github. It is free to download, but comes with no support or warranty,
Github XDIP API example

There are two Windows applications available to download to demonstrate the API. The software is provided 'as is' without support or warranty of any kind.

Best Practices

  • Do not keep the HTTPS port open. When making a request, simply send the API command, wait for the response and then close the connection. There is no guarantee that the HTTPS connection that you initially establish will always remain open.
  • The API is restful based, this means that you have to periodically request information from the XDIP and compare the previous and latest responses to see what has changed. Be careful not to continuously send API requests as they consume resources on the XDIP.

Important Information

  • The XDIP units requires firmware version v1.05 or above.
  • By default, access to the API on the receiver is disabled. To enable the API:-
    • Open the receivers OSD
    • Click on the Advanced page
    • Tick Enable Remote Control option in the Network Info tab.
    • Click the Apply button.
  • The API connects over HTTPS, it requires SSL/TSL version 1.2.
  • The XDIP Receiver has a self-signed certificate. See Exporting an SSL Certificate to access the certificate.
  • To connect to the API, you use port 8443. For example https://<IPADDRESS>:8443/api/<PARAMETERS>
  • Each Receiver is controlled independently.
  • There are no configuration options available in the API.

Changing Channel

  • An access token is required to instruct the receiver to change the channel.
  • You must set an Access Password on the Receiver. This is either chosen when you initially configure the Receiver or changed under the General settings.
  • To acquire the token, you use the /nodes/self/access API path and supply the access password.
  • A token is only valid for one day.

API

The Base URL is http://<IPADDRESS>:8443/api where <IPADDRESS> is the IP address of the XDIP receiver. For example, in order to retrieve a JSON response showing a list of the configured channels you would send http://<IPADDRESS>:8443/api/channels.

Working with JSON is beyond the scope of this wiki, however, there are plenty of resources online that will help you to interact with this product.

To disconnect the current channel you use id 2147483647 which in hex is 0x7fffffff, for example: http://<IPADDRESS>:8443/api/channels/2147483647/switch.

Channels

GET /channels

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:

None

Response:

[
  {
    "id": 0,
    "nodes": [
      {
        "nodeUuid": "string"
      }
    ]
  }
]

Status Code

200: OK
304: Not Modified
500: Operation Failed


GET /channels/{id}

Get details of a single channel.

Parameters:

id = channel id

Response:

{
  "id": 0,
  "nodes": [
    {
      "nodeUuid": "string"
    }
  ]
}

Status Code

200: OK
404: Channel Id Not in Supported Range
500: Operation Failed


GET /channels/connected

Get the channel the receiver is currently connected to.

Parameters:

None

Response:

{
  "id": 0
}

Status Code

200: OK
304: Not Modified
500: Operation Failed


POST /channels/{id}/switch

Switch receiver to the specified channel.
You must provide an Authorization (JWT) token in the Post header. The token is sourced when using the /node/self/access command.

Parameters:

None

Response:

''None'

Status Code

204: 'Successful''
401: Unauthorised. Invalid Access Credentials Provided
404: Channel Id Not in Supported Range
500: Operation Failed


GET /channels/maximumAllowed

Get the maximum number of channels supported by this node.

Parameters:

None

Response:

{
  "count": 0
}

Status Code

200: OK
304: Not Modified
500: Operation Failed


GET /channels/status

Get the status for the currently selected channel.

Parameters:

None

Response:

{
  "summary": "disconnected",
  "connections": [
    {
      "id": "string",
      "state": "disconnected",
      "status": "unknown"
    }
  ]
}

Status Code

200: OK
304: Not Modified
500: Operation Failed



Nodes

GET /nodes/{uuid}

Get details of a single node.

Parameters:

None

Response:

{
  "uuid": "string",
  "name": "string",
  "description": "string",
  "type": "transmitter",
  "active": true,
  "serialNumber": "string",
  "macAddress": "string"
}

Status Code

200: OK
304: Not Modified
404: UUID Not Found
500: Operation Failed


GET /nodes/selected

Returns a list and details of the configured Channel nodes.

Parameters:

None

Response:

[
  {
    "uuid": "string",
    "name": "string",
    "description": "string",
    "type": "transmitter",
    "active": true,
    "serialNumber": "string",
    "macAddress": "string"
  }
]

Status Code

200: OK
304: Not Modified
500: Operation Failed



Access

POST /nodes/self/access

Obtain an Access / Admin JSON Web Token (JWT)

Parameters:

{
  "accessPassword": "string"
}

Response:

{
  "accessToken": "string"
}

Status Code

200: OK
400: Invalid Content
401: Unauthorised. Incorrect password
500: Operation Failed



LocalComputer

GET /localComputer

Get information relating to the computer that is connected to this node.

Parameters:

None

Response:

{
  "name": "string",
  "description": "string"
}

Status Code

200: OK
304: Not Modified
500: Operation Failed


Page last modified on Friday January 15, 2021 14:15:59 GMT-0000