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.
- A simple application that can control a single XDIP Receiver: Download XDIP Demo Application
- A controller that allows you to create Presets and control multiple Receivers called the XDIP Controller.
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