Invocation methods

The edge OpenAPI provides services on port 9999. To ensure secure transmission, all API operations must use the HTTPS protocol.

Authentication and authorization

The OpenAPI uses cookie-based authentication. Before you call other API operations, you must call the CreateAuthCookie operation to obtain an authentication cookie. The steps are as follows.

1. Log on to the IoT Edge gateway console at the following address to configure API access permissions:

   https://{ip}:9999

   In the address, {ip} is the IP address of the machine where the gateway is deployed.

   Note For more information about how to log on to the IoT Edge gateway console, see Log on to the IoT Edge gateway console.
2. Call the CreateAuthCookie operation to create an authentication cookie.
   CreateAuthCookie operation uses Basic Authentication. The authentication identity is passed in the Authorization field of the HTTP request header.

   The `Authorization` field uses the following format:

   Authorization: Basic <base64(username:password)>

   In the format, base64(username:password) represents the Base64-encoded string of <username:password>, which is used to log on to the IoT Edge gateway console.

   For example, if the username is `admin` and the password is `admin1234`, the Authorization field is as follows:

   Authorization: Basic YWRtaW46YWRtaW4xMjM0

3. Retrieve the value of the Set-Cookie parameter from the HTTP response header of the CreateAuthCookie operation.
   Set-Cookie field uses the following format:

   Set-Cookie: token=d71020ad5cb58faf04a6fd81d6df9680582b987eb6d0ce7b33bc3a3e4f******; Max-Age=3600; Path=/

4. Use the value of the Set-Cookie parameter from the response header of the operation as the value of the Cookie parameter in the HTTP request headers for other API operations.
   The Cookie parameter in the HTTP request header uses the following format:

   Cookie: token=d71020ad5cb58faf04a6fd81d6df9680582b987eb6d0ce7b33bc3a3e4f******; Max-Age=3600; Path=/

5. When you call OpenAPI operations other than CreateAuthCookie, pass the authentication token in the Cookie field of the HTTP request header. IoT Edge then validates that the token grants access permissions for the API operation.

Response specifications

• Status code: Response status codes follow HTTP specifications. For more information about status codes, see Status codes.
• Response header: The response header must include the following default field values:

  Server: openresty/1.13.6.2
  Date: Thu, 31 Oct 2019 07:51:57 GMT
  Content-Type: application/json; charset=utf-8
  Transfer-Encoding: chunked
  Connection: keep-alive

• Response body: The response body is in JSON format or is empty.
  • If the API operation is successful, the format and content of the response vary depending on the operation. For more information, see the documentation for the specific API operation.
  • If an error occurs when you call an API operation, the response status code does not start with 2** (such as 302 or 400). The response body contains an error message in the following format:

    {
      "Code": "string", // What kind of error, such as InvalidParameter.
      "Message": "string" // Detailed description about the error.
    }