The KV NDI Device HTTP API allows you to manage and control Kiloview NDI embedded encoder and decoder devices by sending HTTP requests to specific URLs, including N3,N4,N30,N40, etc. The current HTTP API version is 1.0.

It should be noted that the current HTTP API is not strictly a RESTful API, and it does not follow the formal definition rules of the RESTful API for we believe that the formal definition of RESTful does not do any goods as for device management and control. In any case, the current version of the HTTP API is simple, easy to understand and easy to use. In addition, if you think RESTful API is necessary for you, please feel free to let us know.

Compared with RESTful API, NDI device HTTP API (Version 1.0) has the following differences:

1. We only use HTTP GET/POST requests, rather than PUT/DELETE or other requests；
2. We only use JSON format as the return result of each API request (RESTful API also in most cases);
3. The result of each API request (success or failure identification), we use the return JSON field to identify it, rather than the HTTP response like RESTful API.

To fully support the HTTP API described in this document, you need to upgrade the firmware of the NDI device to a version with a major version number of 1.50 or higher. Earlier versions may not fully support these APIs or have compatibility issues.

Basic Rules

URL rules

For HTTP access:

http://<host-ip>[:80]/api/v1/<module-name>/<method-name>

For HTTPS access:

https://<host-ip>[:443]/api/v1/<module-name>/<method-name>

Embedded NDI Devices both support HTTP and HTTPS access, which can be distinguished by URL http:// or https://. The HTTP service port is 80 by default, and the HTTPS service port is 443 by default. <host-ip> is the host IP address corresponding to the NDI device you want to request, which is required.

In the URL path, /api/v1 is used to distinguish the version of the HTTP API. This address may change with subsequent version updates.

<module-name> is the function module name corresponding to the HTTP API. This document will describe the details of each module in detail; <module-name> may be a single word, such as user, tally, … etc.; It may also be in the form of paths separated by /, such as decoder/preset, decoder/discovery, … and so on. See the specific description in the document for details.

<method-name> is a method in the corresponding module, for example: /api/v1/user/add, add is the method of adding users in the user module.

HTTP Request

You can submit a request to the corresponding HTTP API methods through HTTP GET or HTTP POST. For methods that require parameters, you can submit parameters in three ways:

A) Submit URL encoded parameters via HTTP GET method

E.g:

http://<host-ip>/api/v1/tally/set?pgm=1&pvw=0

Another example of url encode special characters (url encode the spaces in the string "My device"):

http://<host-ip>/api/v1/encoder/ndi/set_config?device_name=My%20device

B) Submit application/x-www-form-urlencoded parameters via HTTP POST method

This is the conventional method of submitting parameters by HTTP POST. This means that the Content-Type in the HTTP Request is specified as application/x-www-form-urlencoded (HTTP default).

E.g:

POST /api/v1/tally/set HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
...

pgm=1&pvw=0

Another example of url encode special characters (url encode spaces in the string "My device"):

POST /api/v1/encoder/ndi/set_config HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
...

device_name=My%20device

C) Submit an object in JSON format via HTTP POST; each field in the Object corresponds to a parameter

This requires that the Content-Type in the HTTP request you submit is application/json , and the Body of the HTTP request is a valid JSON object.

E.g:

POST /api/v1/tally/set HTTP/1.1
Content-Type: application/json;charset=utf-8
...

{"pgm":1, "pvw":0}

Another example:

POST /api/v1/encoder/ndi/set_config HTTP/1.1
Content-Type: application/json;charset=utf-8
...

{ "device_name": "My device" }

If there is no special statement in this document, then the above three methods of submitting HTTP request parameters are all valid and have the same effect.

You can use tools like curl, Postman or write your own simple javascript program to complete the HTTP API test.

HTTP response and error handling

Unless the Web server of the device has an exception while working, the device will always give you an HTTP 200 OK response, and include a JSON object in the HTTP Content describing the result of the corresponding API execution.

If the device gives you a response other than 200 OK, it means that the Web server has an abnormal operation. For example, a 404 error indicates that the corresponding request address cannot be found (URL error). Please refer to the HTTP error code and further check the HTTP response error message for the detailed error reason.

Please note: If your HTTP API request address is correct, even if this API fails to execute, the device’s Web server will still return 200 OK. You should determine the success of the execution by checking the fields in the returned JSON object. This is the biggest difference between the current version of the HTTP API and the RESTful API in terms of execution rules.

If the HTTP API is executed successfully, the returned JSON object format is as follows:

{
    "result": "ok",
    "msg": "description message",
    "data": {
        ...
    }
}

Among them, "result" is a field that must exist, and its value "ok" indicates that the requested HTTP API was successfully executed. For successful execution, "msg" does not necessarily exist, you can completely ignore its existence, it is only used to describe some additional information. For HTTP APIs that return results, the "data" field will exist, and it is a JSON object or array, which means the API returns the result. This will depend on the specific API, please refer to the specific API description.

If the HTTP API fails to execute, the returned JSON object format is as follows:

{
    "result": "error",
    "msg": "error message"
}

"result" is a field that must exist. In the current version of the HTTP API, only "error" is defined to indicate that the execution failed, and "auth-failed" indicates that the security verification failed; but In future versions, it may have other not "ok" symbols to represent more error meanings. If "result" is not "ok", you can further check "msg" to determine the cause of the error. See the description of each API for details.

Content-Type of HTTP response must be application/json.

Please note: In the subsequent API descriptions of this document, if necessary explanations for non-special circumstances, explanations about API request errors will be ignored.

Charset

The current version of the HTTP API only supports the utf-8 character set.

Timeout

When you handle the timeout setting of HTTP requests / responses, please note:

• For most APIs, from accepting the request to completing the execution, the device will complete the response within 0.1s; but you need to consider the transmission delay and other factors according to the actual network environment, and set a reasonable timeout value (in general It is recommended to set a timeout of 5 seconds or higher).
• However, you need to pay special attention to the following APIs. Their execution / response time should be specially set, and even require special processing (please refer to the corresponding API description for details):
  • /api/v1/sys/reconnect (reset NDI connection)
  • /api/v1/sys/reboot (reboot the device)
  • /api/v1/sys/restore (restore factory settings)
  • /api/v1/mode/switch (switch between encoding and decoding mode, for Connect Spark IO devices)
  • /api/v1/network/set (modify network settings)

Cross-domain Request

NDI Devices supports HTTP Cross-domain Request, but you need to follow the security rules described in Section 2 of the document.