IoT Platform:Custom service API

Prerequisites

You have created metrics and storage tables for your data sources. For more information, see Metric overview and Custom storage tables.

1. In the IoT Platform console, go to the Overview page and click the ID or alias of the target Enterprise Edition instance.

2. In the left-side navigation pane, choose Data Service > Data API.

3. On the Data API page, click the custom service API tab, and then click Create API.

4. In the Create API wizard, configure the settings in the API basic information section, and then click Next.

   Parameter	Description
   API name	Enter a name for the API. The name can contain Chinese characters, letters, digits, underscores (_), and hyphens (-), and can be up to 30 characters long.
   API path	Enter the API path. It serves as a unique resource identifier within the instance. When you call the API, the value of the apiPath request parameter must match this path. The path must start with a forward slash (/) and can contain letters, digits, underscores (_), and forward slashes (/). The path can be up to 128 characters long. For example: /pk/temperatureMax. Important You cannot change the API path after the API is published.
   API tag	Enter the tag content and press Enter. A tag can contain Chinese characters, letters, digits, underscores (_), and hyphens (-), and can be up to 30 characters long. Use tags as custom identifiers to help you manage your APIs. Important You can add a maximum of five tags to an API.
   API description	Enter a description for the API, such as its purpose and capabilities.
   Response format	The response data format is fixed to JSON.

5. On the Configure and test parameters page, complete the following settings.

   Category	Parameter	Description
   Data source	Metric	Select a specific metric field and dataset. A dataset is a specific organization of objects within a metric field, such as a specific product in the product field or a specific device in the device field. For more information about metrics, see What is a metric?.
   	Storage table	Select a custom storage table that is generated by a data parsing or SQL analysis task. For more information, see Cold storage table.
   Configure parameters	Dataset	This setting appears only after you select Metric as the data source and specify a metric field and dataset. Click Preview Data to go to the details page for the selected data source.
   	Data scope	This setting is displayed only if you select Metric as the data source. Select the data scope for the API: derived metric: Data obtained from raw metrics, original definitions, and derived definitions by using aggregate calculations such as sum and average. derived definition: A metric derived from an original definition and applied to sub-entities. For more information about derived metrics and definitions, see Metric types.
   	Request parameters	Click Add Parameter to add metrics from the selected data source as request parameters for the API. Only system fields and primary key fields of a custom storage table are supported. For each parameter, you must configure its binding field, name, type, operator, whether it is required, an example value, and a description. Important If the parameter type is numeric, the LIKE operator is not supported.
   	Response parameters	Click Add Parameter to add metrics from the selected data source as response parameters for the API. For each parameter, you must configure its priority, binding field, name, type, whether it is used for sorting, an example value, and a description. Select the Select All Parameters checkbox on the right to include all table fields in the API response. Note Sorts the results by this field in either ascending or descending order. Each metric can be configured as only one response parameter.
   	Sort order	Select the order in which to sort the parameters. Ascending (default): Parameters are sorted in ascending order. Descending: Parameters are sorted in descending order.
   Advanced Settings	Enable paginated response	Specifies whether to enable pagination for the response. Disabled: Returns a maximum of 100 results. Enabled: Returns all results in pages. If you enable this feature, the following common parameters are automatically added: pageNum: The page number. pageSize: The page size. The maximum value is 100.
   	Timeout error setting	If an API call exceeds 8 seconds, a timeout error is returned. This setting cannot be modified.

   After you complete these settings, enter test values for the request parameters in the Test API section and click Start Test.

   View the sample data on the Response Example tab, or click Request Details to see specific request information. If the test succeeds, the Response Example tab displays the JSON response, including fields such as errCode:0 and errMsg:"success". A Test succeeded message and the API call duration appear at the bottom.

6. Click Publish.

   Important

   • Before you publish an API, ensure that it passes the test.

   • If you only click Save, the API is saved with an offline status.

   • For an API with incomplete configurations, you can click Edit to complete the configuration and then publish it.

   • You can delete only offline APIs.

   On the Published successfully page, click Create Another to create more custom APIs, or click View in List to view the API in the list.

Next steps

After you create a custom service API, you can call it to retrieve data. For instructions, see Manage and use APIs.

For call examples, see:

• Java SDK call example

• Node.js SDK call example