Introduction

The IoT core is a fully hosted platform service, which can establish secure two-way connections between smart devices and cloud to realize secure and stable message transmission from device to cloud and cloud to device through mainstream IoT protocol (such as MQTT) communication. IoT Core API mainly provides device-related creation, deletion, query and other functions in a Resultful API form.

Calling Mode

Overview

The IoT Core API is designed in a Restful style, with each API function (also known as resource) uniquely identified by using a URL (Universal Resource Identifier). The request mode for resources is to send standard HTTP request to URL corresponding to the resource, such as GET, PUT and POST, etc.; meanwhile, the request is required to comply with the signature algorithm and contains agreed request parameters.

General agreement

• All encodings are UTF-8
• The date format is yyyy-MM-dd, such as 2015-08-10
• The time is shown in UTC format: yyyy-MM-ddTHH:mm:ssZ,such as 2015-08-20T01:24:32Z

• Content-type为application/json; charset=UTF-8

  • The key of object type must be enclosed by double quotation marks (")
  • The key of object type must be represented with lowerCamelCase

Public Request Header

Public Response Header

Response Status Code

The response status code returned follows RFC 2616 section 6.1.1

• 1xx: Informational - Request received, continuing process.
• 2xx: Success - The action was successfully received, understood, and accepted.
• 3xx: Redirection - Further action must be taken in order to complete the request.
• 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
• 5xx: Server Error - The server failed to fulfill an apparently valid request.

General Error Return Format

When the calling interface fails, the general error format is returned. The status code returned HTTP is 4xx or 5xx, and the message body returned includes the globally unique requests, error codes and error message. The caller can locate the problem according to the error code and error message, and when the cause of error cannot be located, you can send a work order to Baidu's technicians, and provide requestid to solve the problem quickly for you.

Definition of message body

Example for error return

{ 
    "requestId": "47e0ef1a-9bf2-11e1-9279-0100e8cf109a", 
    "code":"NoSuchKey", 
    "message":"The resource you requested does not exist"   
} 

Public Error Code

Signature Authentication

The IoT core suite API will authenticate the identity of each access request to ensure the security of the user. Access Key and request signature mechanism are adopted for security authentication. Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings and are officially issued to users by Baidu AI Cloud. The Access Key ID is used to identify the user, and the Access Key Secret is a key used to encrypt the signature string and the signature verification string on the server side, which shall be kept strictly confidential.

For each HTTP request, the user needs to generate a signature string as described below, and place the authentication string in the Authorization header field of the HTTP request.

Format of the signature string

bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}

Among them,

• Version is a positive integer, with the value of 1.
• The timestamp stands for the time when the signature is generated. Time format conforms to [General Contract](#General Contract).
• The expireTime indicates the validity period of the signature in seconds, which is calculated from the time specified by timestamp.
• The signedHeaders stands for the header list involved in the signature algorithm. The headers are separated by a semicolon (;), e.g. host; x-bce-date. The list is arranged in lexicographic order. When the signedHeaders is null, the default value is taken.
• The signature is represented by hexadecimal system with 256-bit signature, consisting of 64 lowercase letters, and the generation mode is given by the following Signature Generation Algorithm.

Signature generation algorithm

For specific introductions to the signature generation algorithm, please see Authentication Mechanism.

Service Domain Name