API Agreement

Introduction

This chapter introduces the elements of the request data and returned data of the API to help you understand how to initiate requests and how to interpret the response data.

• Request Protocol: HTTP

• Request Method: By default, data requests, submissions, and file uploads are done using the POST method. Some APIs also support the GET method, such as Check factory reset permission, determined by each functional interface.

• Request Domain: The device network card IP (IPv4) address, such as http://192.168.66.1

• Request Headers: Provides additional information about the request via HTTP Header. The following is an example of what is used in the API requests.

  • Content-Type: The content type, used to define the type and encoding of network files and web pages.

    The API mainly includes the following two syntax formats:

    1. Content-Type: application/json; charset=utf-8, used for data requests or submissions, encoded in UTF-8 and encapsulated in JSON format.

    2. Content-Type: multipart/form-data; boundary=${boundary}, used for file uploads, supporting image, video, music, and firmware.

  • Cookie: Data stored on the user's local terminal, used in the API to identify user identity, such as Cookie: sid-A506220808450=6062n8wqjz9mm7m7op91a05j58bup424

• Request Body: Allows additional data to be passed to the API in the form of HTTP Body. These parameters can be required or optional, determined by each functional interface.

• Response Body: Response data in the form of HTTP Body. When the HTTP status is 200, it returns data in JSON format; otherwise, it is the corresponding HTTP error code.

• Login Authentication Method: Carry sid-xx=xxxxxxxxx in the Cookie. Some APIs do not require authentication, such as: Ping test.

• [xxx]: Substitute identifier for a type of data.

  • [IP], the IP address of the device's network card, which should be replaced with actual content when used, such as: 192.168.66.1
  • [port], port number, which should be replaced with actual content when used, such as: 8080.
  • [serial number], the device's serial number, which should be replaced with actual content when used, such as: A506220808450.

Submitting Requests

Data Requests and Submissions

When making data requests and submissions, the attached data should be encoded in UTF-8 and encapsulated in JSON format.

Example 1: Adding a user (Login authentication required)

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"
    }

Example 2: Testing device network connection (No login authentication required)

Request Headers

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

Request Body

None

File Upload

When uploading files, the attachment data should be encapsulated in binary form, for example:

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--

Response

All response data is in JSON format.

The status/result attribute in the JSON object is the Common Error Codes. A value of 0 indicates that the data retrieval or operation was successful, otherwise, it represents the corresponding error code for failure.

Example 1: Single-level data encapsulation

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

Example 2: Data encapsulation with secondary objects

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

Example 3: Data encapsulation with secondary objects as arrays

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

Example 4: Data encapsulation with business errors

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

Login Authentication and API Access Verification

To ensure system security, most of API calls in this doc require authentication, and some APIs are accessible only to administrators, such as: Add a user and Delete a user.

Login Authentication

Login using the username and password.

Upon successful login, the Session ID will be stored in the Cookie:

Cookie: sid-[serial number]=6440wa6u5wfw8wv43f91v55cqkctnpv6

The Session ID remains valid until the device is turned off or restarted.

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 Access Authentication

When accessing an API that requires authentication, the Session ID obtained from the login authentication interface must be transmitted in the Cookie.

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