This topic describes common information for calling IoT Platform APIs, including gateway protocols and addresses, call methods, request parameters, and response parameters.
Client APIs and cloud APIs use different AppKey and AppSecret pairs for identity authentication. IoT Platform issues the AppKey and AppSecret. You can obtain them as follows:
Client: Obtain the AppKey and AppSecret from the platform. For more information, see Create your own app.
Cloud: Obtain the AppKey and AppSecret from the platform. For more information, see Obtain a cloud AppKey.
API gateway protocol and address
When you send an API call request, the API gateway verifies the signature that contains the AppSecret. If the verification fails, the request is discarded and a 401 error code is returned. The API gateway uses the HTTPS protocol. The gateway addresses are as follows.
Data center | Region ID | Gateway address |
China (Shanghai) | cn-shanghai | api.link.aliyun.com |
Singapore | ap-southeast-1 | ap-southeast-1.api-iot.aliyuncs.com |
Germany (Frankfurt) | eu-central-1 | eu-central-1.api-iot.aliyuncs.com |
US (Virginia) | us-east-1 | us-east-1.api-iot.aliyuncs.com |
How to call APIs
IoT Platform provides client APIs and cloud APIs, along with software development kits (SDKs) and call examples for the following languages.
Device-side | Supported languages | SDK or call example |
Client |
| |
Cloud |
|
If you want to use another language to call the APIs, you must implement the signing logic for that language. For more information, see Signing mechanism.
Common request parameters
All IoT Platform APIs follow a consistent request parameter specification. The following fields are common parameters that you must include in every API call.
Parameter | Subparameter | Type | Required | Description |
id | - | String | Yes | The request ID. If you use an SDK provided by IoT Platform, this ID is automatically generated. If you call the API yourself, you must generate this ID. This parameter is used to associate requests with acknowledgements and for troubleshooting. |
version | - | String | Yes | The version number of the Open Platform. The value is fixed at |
request | - | - | Yes | The system request parameters. |
- | apiVer | String | Yes | The version number of the API that you call. For more information, see the documentation for the specific API. |
- | iotToken | String | Yes | This parameter is valid only when you call a client API. It is used to confirm the system parameters of the request initiator. If you use the account SDK provided by IoT Platform, this value is automatically generated. |
- | cloudToken | String | Yes | This parameter is valid only when you call a cloud API. You must use the project ID to obtain the corresponding token. For information about the specific API, see the "Obtain a cloud resource token" section in Cloud resource service. |
- | language | String | No | Used to pass multilingual information. This parameter is valid only when you call a client API. |
params | - | - | No | The business request parameters. The content varies by API. Some APIs do not require these parameters and operate based on default user authentication information. For more information, see the documentation for the specific API. |
Common response parameters
All IoT Platform APIs follow a consistent response parameter specification. The following fields are common parameters returned in every API call.
Parameter | Type | Required | Description |
id | String | Yes | Used to identify the request record. This is the corresponding request ID. |
code | Int | Yes | The return code of the API. A value of 200 is returned for a successful request. If the request fails, a detailed error code is returned. For more information about error codes, see Error code dictionary. |
message | String | Yes | The message returned by the API. A value of success is returned for a successful request. If the request fails, the cause of the error is returned. |
data | - | No | The return value of the API. The return value of each API can be customized. Some APIs do not have a return value and only use the return code to indicate whether the request was successful. |