接口约定

概述

本篇介绍了 API 的请求数据和返回数据的构成元素，通过这些元素你可以了解如何发起请求，如何解读返回数据。

• 请求协议：HTTP

• 请求方法：默认情况下，数据请求、提交及文件上传都用 POST 方式，个别 API 同时支持 GET 方式，如：重置设备鉴权，具体由各功能接口决定。

• 请求域名： 设备网卡 IP（IPv4） 地址，如：http://192.168.66.1

• 请求头（Request Headers）：以请求头（HTTP Header）提供有关请求的的额外信息，以下是本文档中 API 的请求中使用的实例

  • Content-Type：内容类型，用于定义网络文件的类型和网页的编码。

    API 中主要包括以下两类语法格式：

    1. Content-Type: application/json; charset=utf-8，用于数据请求或提交，使用 UTF-8 编码并以 JSON 格式封装。

    2. Content-Type: multipart/form-data; boundary=${boundary}，用于文件上传，支持图片、视频、音乐等媒体文件及产品 固件。

  • Cookie：储存在用户本地终端上的数据，在 API 中被用于辨别用户身份，如 Cookie: sid-A506220808450=6062n8wqjz9mm7m7op91a05j58bup424

• 请求参数（Request Body）：允许以消息体（HTTP Body）的形式将附加数据传递给 API。这些参数可以是必要的，也可以是可选的，具体由各功能接口决定。

• 返回数据（Response Body）：以消息体（HTTP Body）的形式返回数据。HTTP 状态为 200 时，返回 JSON 格式的数据，否则为 HTTP 对应错误码。

• 登录认证方式：在 Cookie 中携带 sid-xx=xxxxxxxxx。个别 API 无需认证，如：Ping测试。

• [xxx]: 某类数据的替代标识。

  • [IP]，设备网卡IP地址，使用时需替换实际内容，如：192.168.66.1
  • [port]，端口号，使用时需替换为实际内容，如：8080。
  • [serial number]，设备序列表号，使用时需替换为实际内容，如：A506220808450。

提交请求

数据请求及提交

数据请求及提交时，要求附加数据使用 UTF-8 编码并以 JSON 格式封装，如：

示例 1：添加用户（需要登录认证）

Request Headers

    POST / HTTP/1.1
    Host: 192.168.66.1/api/user/add
    Content-Type: application/json; charset=utf-8
    Cookie: sid-A506220808450=6062n8wqjz9mm7m7op91a05j58bup424

Request Body

    {
        "username":"test",
        "password":"c4ca4238a0b923820dcc509a6f75849b"
    }

示例2：测试设备网络连接（无需登录认证）

Request Headers

    POST / HTTP/1.1
    Host: 192.168.66.1/api/ping
    Content-Type: application/json; charset=utf-8

Request Body

None

文件上传

文件上传时，要求附件数据以二进制形式封装，如：

Request Headers

    POST / HTTP/1.1
    Host: 192.168.66.1/mwapi/upload-source-file
    Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryuCSyGCncblrUp3ed
    Cookie: sid-A506220808450=6062n8wqjz9mm7m7op91a05j58bup424

Request Body

    ------WebKitFormBoundaryuCSyGCncblrUp3ed
    Content-Disposition: form-data; name="file"; filename="204.jpeg"
    Content-Type: application/octet-stream
    XXXX
    XXXX
    ------WebKitFormBoundaryuCSyGCncblrUp3ed--

返回数据

返回数据均为 JSON 数据格式。

JSON 对象中的 status/result 属性为 公共错误码，为 0 时表示数据获取或操作成功，否则为相应的失败错误码。

示例1：单层的数据封装

    {
      "status": 0,
      "code": "Success",
      "enable": true,
      "enable-web-control": true
    }

示例2：带有二级对象的数据封装

    {
      "result": 0,
      "info": {}
    }

示例3：二级对象为数组的数据封装

    {
      "status": 0,
      "items": []
    }

示例4：出现业务错误的数据封装

    {
      "status": 16,
      "message": "Item is not exist."
    }

登录认证及 API 访问身份验证

为保障系统安全，本文档中的 API 大多数需要进行身份验证，部分 API 要求管理员才可访问，如：添加用户、删除用户等。

登录认证

使用用户名username和密码password登录。

登录成功后会在 Cookie 存放 Session ID：

Cookie: sid-[serial number]=6440wa6u5wfw8wv43f91v55cqkctnpv6

Session ID 持续有效，直到设备关机或重启。

Request Headers

    POST / HTTP/1.1
    Host: 192.168.66.1//api/user/login
    Content-Type: application/json; charset=utf-8

Request Body

    {
        "username":"test",
        "password":"c4ca4238a0b923820dcc509a6f75849b"
    }

Response Headers

    Content-Type: application/json; charset=utf-8
    Expires: 0
    Set-Cookie: sid-A506220808450=6062n8wqjz9mm7m7op91a05j58bup424

Response Body

{
    "status":"test",
    "sid":"6440wa6u5wfw8wv43f91v55cqkctnpv6"
}

API 访问身份验证

需要身份验证的 API 访问时，需要在 Cookie 中传输登录认证接口获取的 Session ID

Request Headers

    POST / HTTP/1.1
    Host: 192.168.66.1//api/user/add
    Content-Type: application/json; charset=utf-8
    Cookie: sid-A506220808450=6062n8wqjz9mm7m7op91a05j58bup424