2. Home
  4. Docs
  6. Kiloview Intercom Server HTTP API
  8. Basic rules

Basic rules

1.1 URL rules

For HTTPS access:

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

All NewTek Embedded NDI Devices 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. \<host-ip> is the host IP address of the NDI device you want to access.

<module-name> is the name of the functional module of the HTTP API, such as user/updateuser, talkback/talk_add.json, etc. Please refer to the document for specific description.

<method-name> is a method in the module, for example: /intercom/user/login.json, login is the login method in the user module.

1.2 HTTP response and error handling

Unless the web server of the device is working abnormally, the device will keep giving you an HTTP 200 OK response, and a JSON object in the HTTP Content will describe the result of the corresponding API execution.

If the device gives you a response other than 200 OK, it means that the Web server is working abnormally. For example, a 404 error means that the request address cannot be found (URL error). Please refer to the HTTP error code and check the error message of the HTTP response to get the detailed cause of the error.

Please note: If your HTTP API request address is correct, even if this API fails to execute, the web server of the device will still return 200 OK. You should check the fields in the returned JSON object to determine whether the execution was successful or not. This is the biggest difference in execution rules between the current version of HTTP API and RESTful API.

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

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

"result" is a must field, and its value "ok" indicates that the requested HTTP API is executed successfully, while"msg" does not necessarily exist, you can also ignore its existence, which 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 return result of the API. Please refer to the description of the specific API.

If the HTTP API fails to execute, the format of the returned JSON object 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" indicates execution failure, and "auth-failed" indicates that security verification failure; but In future versions, it may have other symbols other than "ok" to indicates more error meanings. If "result" is not "ok", you can check "msg" to get the cause of the error. Please refer to the description of each API for details.

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

Please note: In the subsequent API description of this document, unless necessary for special circumstances, the description about API request errors will be ignored.

1.3 CHARSET

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

1.4 Timeout

When you process the HTTP request/response timeout settings, please note:

  • For most API, from receiving the request to completing the execution, the device will response within <= 0.1s; but considering the transmission delay and other factors according to the actual network environment, please set a reasonable timeout value (generally, it is recommended to set a timeout of 5 seconds or higher)

How can we help?