约定

API接口的风格特点

一般约定

本文档中规定，除非特殊说明：

定义的接口采用RESTful风格；

• 请求和回应数据的内容为JSON格式，编码方式统一采用UTF-8。

• URL中带$的字符串为变量，例如：

$APISERVER：API服务器主机名，本文档中均为api.c.inhandnetworks.com或api.g.inhandnetworks.com。

$AUTHSERVER：授权服务器主机名，本文档中均为auth.c.inhandnetworks.com或auth.g.inhandnetworks.com。

$XXX：参数

• 时间（创建、更新、登录、退出等）均采用4字节整数，表示从CUT（Coordinated Universal Time）时间1970年1月1日00:00:00（称为UNIX系统的Epoch时间）到当前时刻的秒数（10位）。

• 所有对单个指定资源操作的接口，如果资源不存在，则返回结果为资源不存在的错误信息。

• 变量命名定义：URL参数中的所有变量，均采用小写字母，单词间以下划线分隔的方式命名。请求消息内容（http的body体、返回结果或消息队列中的消息体）中的变量，均采用JAVA中局部变量的命名方式，即：变量中第一个单词首字母小写，其他单词首字母大写，单词间无分隔符。

• 所有接口中，请求消息内容以及返回结果中的”$变量名”表示该章节中定义的对应的数据结构体，一般为JSON对象。如“$UserInfo”表示用户管理接口定义一章中的小节“用户信息数据结构定义”中定义的用户信息JSON对象格式。

• 每一章中的数据结构定义中的字段说明，若字段有“创建/更新时忽略请求中的该项参数”，则表示该字段在创建或更新资源接口的请求消息内容中不携带。如用户管理接口一章中的用户信息数据结构定义中的“oid”字段，在创建用户和更新用户信息接口中的请求消息内容“$UserInfo”中不需携带该字段。

• 除oauth2的相关接口以及内部接口外，其他接口的访问URL均需携带“access_token”字段。

• 密码都采用md5加密传输。

• 系统内部API保留字段：oid_user, uid_user, ip_user, username_user,resourceIds

• 主干版本的所有日志代码为7位数字。

定义

API接口的对象

• 设备：控制器、网关等物理实体，包含端口属性

• 端口：设备的对外连接接口，包含物理端口（串口、网口等）和逻辑端口（协议等）属性

• 控制器：客户的设备，独立的信息源

• 网关：一般为映翰通的网络设备，不仅是独立的信息源，还负责传递其它设备（一般为控制器）的信息

• 机型：设备的型号，包含了机型描述、图片、文档、数据变量、监控视图（组态）等属性

• 现场：设备及其连接关系（可以为空），并可以包含文字描述、图片、文档等属性

• 工程、站点：等同于现场

• 机构、租户：本系统的一个独立、完整的管理单位，从属于不同机构的用户、角色、设备、现场等资源完全独立，数据完全隔离。

接口访问级别定义