上屏API-概述

Posted 2020-10-31

1.概述

1.1.用途及阅读方法

上屏API是上屏系统的后台接口，管理平台界面实现需要遵循本接口规范。

1.2.通信协议

客户端和服务器通过HTTP协议通信，客户端使用HTTP GET方法或POST方法向服务器发送请求，服务器返回json格式的业务数据或操作结果给客户端。
尽管接口同时支持GET和POST方法，建议查询数据时使用GET方法，修改和添加数据时使用POST方法。

1.4.接口请求

接口的请求地址是个URL地址，每个接口URL地址都包括接口位置和请求参数，例如：

http://ip/res/?action=get&token=123456  

其中：
http://ip/res/ 是接口请求的URL位置，“ip”在实际请求中要替换成服务器的ip地址或域名。
符号?后面是参数列表，以name=value的形式体现。
其中：
action参数是在所有接口中都要有的，该参数表明了请求业务的类型。
token参数提供一个安全认证符号给服务器，服务器用token来验证客户端的合法性，除了登录验证接口之外，其他接口都需要token参数。
所有参数都可以采用GET或POST方法提交。在使用ajax提交时，应当在接口位置结尾加上反斜杠"/"，以免参数提交失败。如：http://ip/res/
有关URL地址的编码规范，请参考HTTP 1.1规范。

1.5.接口响应

服务器在收到接口请求后，首先判断token的正确性，如果token错误，则返回认证错误的消息给客户端。如果token正确，服务器返回json格式的文本内容给客户端。返回给客户端的json文本描述了服务器对请求的处理结果和响应数据。

1.6.接口安全

客户端必须首先通过身份认证才能继续调用接口，在一个“挑战—>应答”模式的身份认证过程中完成身份认证，认证通过后，服务器为客户端分配一个临时令牌token，在后续的请求中，token作为一项必选参数提供，服务器通过token识别用户身份和验证请求的合法性。
在没有接口调用时，token的有效期为30分钟，之后客户端再调用接口时必须重新进行身份认证，获取新的token。
为了确保一定的安全性，客户端应妥善保存token值。

1.7.URL编码

当URL请求参数值中包含URL地址保留字符时，应对参数值进行URL编码。
具体参见“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
当请求参数包含中文字符时，应对中文字符采用UTF-8编码。

1.8.描述约定

本文档在描述接口的URL地址时，如果没有特殊说明，会省略掉URL前面的相同部分。
例如，
http://ip/res/?action=get&token=123456 简化为 res/?action=get&token=123456
在描述参数时，省略token参数的描述，在示例中也会省略。在实际调用中必须把token参数加上。
在对参数进行描述时，用【必选】表示该参数必须提供，【保留】表示该参数可以接受但尚未被使用。

1.9.返回消息结构

返回的json消息数据结构具有严格的一致性，客户端可以采用一致的接收和解析方式处理返回消息。
简单消息
简单的返回消息包含对请求的处理结果，结构如下：

{
    "code":0,
    "err_desc":""
}

其中：
code 为 0 表示处理成功，其它值表示处理失败。
err_desc是对错误的描述，在code为0时err_desc会被省略。
特殊情况，在用户认证的login1和login2接口中，err_desc具有特殊用途用法，具体参见接口描述。除这两个接口之外，err_desc都表示错误描述。

带业务数据的消息
有的返回消息除了包含处理结果信息，还包含业务数据记录集，结构如下：

 {
        "code":0,
        "data":{
            "count":1,
            "items":[{
            "server":"g3",
            "ip":"127.0.0.1",
            }]
        }            
    }

其中：
data 业务数据的根节点：
count 业务数据的条数，可能的值为0 ~ n
items 业务数据，是一个数组，数据条数由count属性定义。当count为0时，items属性可能为null或者不存在。
本文档后续章节中，在描述items元素的属性时，会省略一些属性的描述，即实际调用接口返回的属性在本文档中可能会没有描述，这种情况下请直接忽略被忽略描述的属性值。本文档中描述的属性是实际返回内容的一个子集，没有描述到的内容对集成本系统没有影响。

带分页数据的消息
如果返回数据较多，服务器会对返回的数据进行分页，客户端可以按照页码请求指定范围的数据。带分页信息的返回数据结构如下：

    {
    "code":0,
    "data":{
        "page":1,
        "page_size":"20",
        "pages":"1",
        "total":"2",
        "count":2,
        "items":[...]
                }
}

分页数据信息在data元素下，意义如下：
page 当前页码
page_size 每页数据记录条数
pages 总共的页数
total 总数据条数
count 当前返回页的数据条数
如果返回的数据带有分页信息，则可以在调用接口时使用page参数来请求指定页码的数据。

1.10.参考

[1] RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1[S].
[2] RFC 3986, Uniform Resource Identifier (URI): Generic Syntax[S].
[3] http://www.json.org/ Introducing JSON