Loading...
 

DDX: Using the API

This is a brief overview of how to access the DDX’s API and how you can interact with it using an online tool. It will not, however, go into the inner workings.

The API on the DDX adheres to RESTful and CORS standards, and can be downloaded from the DDX itself using the following URL:-

http(s)://<IPADDRESS>/rest-api

It is presented in a YAML format, which is a human-readable data serialisation language.

A copy of the YAML file taken from a DDX running 3.03 can be downloaded from the link below:-
Download DDX API version 3.0.41

Best Practices

  • Do not login and generate a new token for every API request, the token is valid for 24 hrs.
  • Do not keep the HTTP 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 HTTP 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 DDX 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 DDX.


YAML Tool

There is an online tool called Swagger that allows you to view the API in an easy format and interact with the API. The DDX requires internet access in order to achieve this.

Open a web browser and go to the Swagger online demo: http://petstore.swagger.io

At the top of the page, enter the URL of the DDX, including the path to the rest-api. Press Explore. E.g. http://10.0.10.14/rest-api

DDX API1

You will be presented with a list of API functions on the DDX. In order to perform any function, you need a token which is provided when you authenticate with the DDX. The token is valid for 24 hours. To acquire the token, click on Expand operations for the Auth function.

DDX API2

In the body section under parameters, enter the username and password for the DDX in the following format.

{
“username”: “username”,
“password”: “password”
}


For example: -

DDX API3

Press the Try it out! button to execute the function.

In the Response body, you should receive a response showing your unique session token.

DDX API4

Now that you have a token, you can use any of the available functions. For example, to see the API version, expand the API operations and in the Authorization field under Parameters enter the following format: bearer <token>

DDX API5

Press the Try it out! button to execute the function.

The response will be something like this:-

DDX API6


Raw Connection Example

Using Telnet and port 80, you can issue the HTML/JSON commands in a RAW form to the DDX. If you are writing a controller application, you will need to ensure it can handle HTML requests and parse the JSON responses appropriately.

A POST or PUT request must include the content length in the header, as you would for any webservice. The content length is the number of bytes (characters) in the body/payload of the request. If this number is not correct, you will either be disconnected from the DDX or receive an error.

The first function that you must perform is authenticating with the DDX to generate a token by sending your Admin login credentials that you use to log into the web interface. The token does not include the double quotes (“).


Request:

POST /api/auth/local HTTP/1.1
Host: 10.0.10.14
Content-Type: application/json;
Content-Length: 43

{"username":"admin","password":"password"}



Response:

HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Cache-Control: max-age=3, must-revalidate
App-Version: 0.3.94
Content-Type: application/json; charset=utf-8
Content-Length: 164
Vary: Accept-Encoding
Date: Wed, 09 Nov 2016 12:34:20 GMT
Connection: keep-alive

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiaWF0IjoxNDc4Njk0ODYwLCJuYmYiOjI4NDg5ODQsImV4cCI6MjkzNTM4NH0.qi5JpApGP8Tcttvw4IW6FK9ldv2BhVd8vWy7PBim1M4"}


To receive information about the DDX, such as its description, location and firmware version, you can use the System information request. For the DDX to accept the request, you must provide the token that was received when you authenticated. Replace TOKEN in the request below with the token provided.


Request:

GET /api/system/systemInfo HTTP/1.1
Host: 192.168.1.22
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN



Response:

HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Cache-Control: max-age=3, must-revalidate
App-Version: 0.3.94
ETag: "b9-YuTkFdP1UR66Ii5k4OeZ4Q"
Access-Control-Expose-Headers: ETag
Content-Type: application/json; charset=utf-8
Content-Length: 340
Vary: Accept-Encoding
Date: Wed, 09 Nov 2016 15:59:08 GMT
Connection: keep-alive

{"description":"AdderView DDX30","location":"Unspecified","systemVersion":"3.00","firmwareVersion":"3.00.0272","recoveryVersion":"1.03.4323","boardVersion":2,"datafpgaVersion":"000b","videofpgaVersion":"00.0b","ignoreFirmwareMismatch":false,"imageType":"PRIMARY","edidId":101,"links":{"self":"/api/system/systemInfo"},"webVersion":"0.3.94"}


To connect a Console to a Computer, you use the consoles request in the following format: -

/api/consoles/{id}/switch

{id} = The ID allocated to the console..

In the body of the request, you specify the computers id, e.g. the port number is it connected to and the view mode which can be either VIEWONLY, SHARED, EXCLUSIVE or PRIVATE. The response will be 204 “No Content” if it is successful.


Request:

POST /api/consoles/1/switch HTTP/1.1
Host: 10.0.10.14
Connection: keep-alive
Content-Length: 48
Content-Type: application/json
Accept: application/json
Authorization: Bearer TOKEN

{
"computerId": 1,
"mode": "VIEWONLY"
}



Response:

HTTP/1.1 204 No Content
X-Powered-By: Express
Access-Control-Allow-Origin: *
Cache-Control: max-age=3, must-revalidate
App-Version: 0.3.94
Date: Wed, 09 Nov 2016 15:46:15 GMT
Connection: keep-alive


More Information

There are many resources on the internet on how to use RESTful (Representational state transfer) API’s/webservices.

Below is a list of useful resource links:-

https://en.wikipedia.org/wiki/Representational_state_transfer
https://www.tutorialspoint.com/restful/restful_introduction.htm
http://restcookbook.com/


Page last modified on Saturday May 4, 2019 10:31:12 BST