2. 主页
  4. 文档
  6. NDI 设备 HTTP API(Version 1.0)
  8. 1. 基本规则

1. 基本规则

URL规则

对于HTTP访问：

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

对于HTTPS访问：

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

Embedded NDI Devices均支持HTTP和HTTPS访问，这可以通过URL的http://或https://进行区分。HTTP的服务端口默认为80，HTTPS的服务端口默认为443。\<host-ip>是对应您要请求的NDI设备的主机IP地址，这是必须的。

URL路径中，/api/v1 用于区分HTTP API的版本，随着后续的版本更新，这个地址可能会发生改变。

<module-name>是HTTP API对应的功能module名称，本文档将详细描述每一个module的细节；<module-name>可能是单一word，例如 user, tally, …等等；也可能是以 / 分隔的路径形式，例如 decoder/preset, decoder/discovery, …等等。详见文档中的具体描述。

<method-name>是对应module中的一个方法，例如：/api/v1/user/add ，add是user模块中的添加用户的方法。

HTTP请求

您可以通过HTTP GET或HTTP POST向对应的HTTP API methods提交请求。对于需要参数的methods，您可以有三种方法提交参数：

A) 通过HTTP GET方法，提交URL encoded参数

例如：

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

另外一个对特殊字符进行url encode的例子（将字符串"My device"中的空格进行url encode）：

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

B) 通过HTTP POST方法，提交application/x-www-form-urlencoded参数

这是常规的HTTP POST提交参数的方法。这意味着HTTP Request中的Content-Type指定为application/x-www-form-urlencoded（HTTP默认）。

例如：

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

pgm=1&pvw=0

另一个对特殊字符进行url encode的例子（将字符串"My device"中的空格进行url encode）:

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) 通过HTTP POST方法，提交JSON格式的object；Object中的每一个field对应一个参数

这要求您提交的HTTP请求中Content-Type为 application/json，而HTTP请求的Body为一个有效的JSON object。

例如：

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

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

另一个例子：

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

{ "device_name": "My device" }

如果在本文档中没有特别声明，那么以上三种方式提交HTTP请求参数都是有效的，作用是等同的。

您可以使用curl、Postman等工具或者自己编写简单的javascript程序来完成HTTP API测试。

HTTP响应和错误处理

除非设备的Web server在工作时出现了异常，否则设备总会给予您HTTP 200 OK响应，同时在HTTP Content中包含一个JSON object描述对应API执行的结果。

如果设备给予您非200 OK的响应，这表示Web server出现了工作异常，例如404错误表示无法找到对应的请求地址（URL错误）。请参考HTTP的错误代码、并进一步检测HTTP响应的错误消息获知详细的出错原因。

请注意：如果您的HTTP API请求地址正确，即使这个API执行失败，设备的Web server仍然会返回200 OK。您应该通过检查返回的JSON object中的字段来确定执行成功与否。这是当前版本HTTP API与RESTful API在执行规则上的最大差异。

如果HTTP API执行成功，返回的JSON object格式如下：

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

其中，"result" 是必定存在的字段，它的值"ok"表示请求的HTTP API执行成功。对于执行成功而言，"msg" 并非必定存在，您也可以完全忽略它的存在，它仅仅用于额外描述一些信息。对于有返回结果的HTTP API来说，"data" 字段将会存在，而且它是一个JSON object 或者 array，表示API的返回结果。这将视具体的API而定，请参考具体API的说明。

而如果HTTP API执行失败，返回的JSON object格式如下：

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

"result"是必定存在的字段，当前版本的HTTP API中，仅定义了"error"表示执行失败，以及"auth-failed"表示安全验证失败；但在未来的版本中，它可能会有其它的非"ok"的标识符号来代表更多的出错含义。如果"result"不为"ok"，您可以进一步检查"msg"来确定出错的原因。详见每一个API的说明。

HTTP响应的Content-Type必定为 application/json。

请注意：在本文档的后续API描述内容中，如非特殊情况的必要说明，将忽略关于API请求错误的说明。

CHARSET

目前版本的HTTP API仅仅支持utf-8字符集。

超时

在您处理HTTP请求/响应的超时设置时，请注意：

  • 绝大多数的API，从接受请求到完成执行，设备会在 <= 0.1s 时间内完成响应；但您需要根据实际的网络环境考虑传输延时等因素，合理设置超时值（一般来说，建议设置5秒超时或更高一些）。
  • 但以下几个API您需要特别注意，它们的执行/响应时间应该特别设置，甚至需要进行特别的处理（详细情况请参考对应的API说明）：
    • /api/v1/sys/reconnect (重置NDI连接)
    • /api/v1/sys/reboot (重新启动设备)
    • /api/v1/sys/restore (恢复出厂设置)
    • /api/v1/mode/switch (在encoding和decoding模式之间切换，对于Connect Spark IO设备)
    • /api/v1/network/set (修改网络设置)

跨域请求(Cross-domain Request)

NDI Devices支持HTTP Cross-domain Request，但您需要遵循文档第2节所描述的安全性规则。

我们要如何帮助您？