API Service

The API service function is to service data, providing data from the system to users through API interfaces. You can grant a user the management permissions for the API service by assigning them the API Management role.

API Service

The API service page displays the APIs in the system. Here, users can see the list of APIs that are available for service (in the published state), and can quickly locate the desired API through the search and type filters in the upper right corner of the page.

On the API service page, you can click on an API to view its details. On the details page, you can learn about the basic information of the API, the call URL, and the request parameters. You can also test the API and view its functional effects.

Tip

The API service page displays all APIs created by users in the system that are in the published state.

API Management

The API management page allows users to manage their own APIs, supporting the creation of four types of APIs: aggregated data API, detailed data API, custom query API, and registered API. Users can perform related operations such as publishing, authorization, rate limiting, and monitoring on the created APIs.

Tip

The API management page displays the user's own APIs and does not display any APIs of other users.

Aggregation Data API

The Aggregated Data API is used to retrieve the aggregated result data of a single chart after data analysis in app creation, including all types of charts supported by the system.

Create Aggregated Data API

Please follow the steps below to create a new aggregated data API.

1. Create a New API. On the API Management page, click New, select Aggregate Data, and the New API (Aggregate Data) page will pop up. 2. Fill in Basic Information. Fill in the API name, API path, request method, select Chart, and other basic information as required on the page. For detailed requirements of the basic information, refer to the table below.

Parameter	Description
API Name	Fill in the API name. The name is limited to Chinese, English, letters, numbers, and underscores, with a length range of 3-128 characters. The API of the current user within the system cannot be duplicated. After publishing, the API must be unique across all users within the system.
API Path	Fill in the API path. Duplicates are not allowed, supports English, numbers, underscores, hyphens (-), and slashes (/). The API path of the current user within the system cannot be duplicated. After publishing, the API path must be unique across all users within the system.
Request Method	Supports both GET and POST methods.
Select Chart	Select the chart that the API will access, the API will return aggregated data of the analysis chart. Limited to charts that the current user has access permissions for.
Data Return Format	Supports both Array and Object formats.
Description	Fill in a brief description of the API to help users quickly understand the scope of this API query.

3. Request Parameter Configuration.

• Configuration of request parameters for GET request method. The data source refers to the chart operated by the API, which can be viewed by creating a new exploration or modifying the chart. Select the fields that need to be used as parameters from the datasets related to the chart and drag them into the right Query parameter area. Users can define the name, default value, and simple description of the parameters themselves for easy identification later. Fields of bool type and json type are not supported as parameters. When there are multiple datasets, the dataset names will be displayed in the Source item. The Source item is not displayed for a single dataset. The red box is the system default parameter, which is unrelated to the dataset, has no bound field, cannot be deleted, and can modify the default value and description. The specific functions of the parameters are as follows.

Parameter	Parameter Type	Parameter Description
needTotalHits	Boolean	Whether to return the total number of rows of requested data. The default is false, which does not return the total number of rows of requested data.
limit	Number	Refers to the total number of records to be obtained, with a default value of 1000, which means obtaining 1000 records.
offset	Number	Refers to the starting position of the returned records, with a default value of 0, indicating that records are obtained starting from the 1st record, with a total of limit records obtained.
orderBy	Text	The field by which the data is sorted, it is recommended to set this.
orderType	Text	Refers to the sorting method of orderBy, supporting three methods: ascending, descending, and no sorting.
orderByFrom	Text	The dataset where orderBy is located, it is recommended to set this. This parameter is displayed when the aggregated chart has multiple datasets.

• Configuration of request parameters for POST request method. Supports both request parameters and JSON parameter configuration methods. The configuration of request parameters for POST method is the same as that for GET method, so it will not be elaborated here. When selecting JSON parameter configuration, it supports filling in JSON examples for API callers to refer to during actual calls.

**4. Verify API Information. ** After the parameter configuration is saved, the API is successfully created with an unpublished status. Users can verify the API information on the API details page. If there are any issues, they can click Edit on the right to make modifications.

Aggregation Data API Testing and Publishing

After creating the Aggregated Data API, it needs to be tested to check if the API functions meet the requirements. Enter the API's details page, click the test button at the top right, and proceed to the test page.

API Testing for Configuring Request Parameters

Test the API for setting request parameters by selecting all parameters to view the returned results. You can also partially select or not select any parameters to view the returned results.

Tip

Supports selecting any query condition (parameter) or all query conditions to execute the query. When no query conditions are selected, the full set of the query is returned. The test example only demonstrates the testing process. Please conduct thorough testing according to the actual scenario to ensure the API meets the requirements.

API Testing Using JSON Method

POST requests support using JSON configuration parameters. During the API creation process, a JSON example is written, and callers can refer to this example to write JSON when making requests. The following test example demonstrates how to refer to the JSON example when sending a request.

API Publishing

API will be released after thorough testing. Once released, the API status will change to Published and Running, and it will be displayed in the API Service for callers to use.

Detailed Data API

The detailed data API is primarily used to retrieve the relevant field information of datasets available within the system, including datasets from the data mart and datasets created by app development.

Create Detail Data API

Please follow the steps below to create a new detail data API. 1. Create API. On the API management page, click New, select Detail Data, and the New API (Detail Data) page will pop up. 2. Fill in the basic information. Fill in the API name, API path, request method, dataset, and other basic information on the page as required. For detailed requirements of the basic information, please refer to the table below.

Parameter	Description
API Name	Fill in the API name. The name is limited to Chinese, English, letters, numbers, and underscores, with a length range of 3-128 characters. The API of the current user in the system cannot be duplicated. After publishing, the API must be unique across all users in the system.
API Path	Fill in the API path. Duplicates are not allowed, supports English, numbers, underscores, hyphens (-), and slashes (/). The API path of the current user in the system cannot be duplicated. After publishing, the API path must be unique across all users in the system.
Request Method	Supports GET and POST methods.
Select Dataset	Select the dataset that the API will access, supporting access to datasets in app creation and the dataset market.
Data Return Format	Supports Array and Object formats.
Description	Fill in a brief description of the API to help users quickly understand the scope of this API query.
3. Request Parameter Configuration.

• Configuration of request parameters for GET request method.

  In the dataset displaying API operations, you can click on the dataset to perform operations on it, such as viewing and adding fields. Then, select the fields that need to be used as parameters in the dataset and drag them into the right Query parameter area. Users can define the parameter names, default values, and simple descriptions themselves, making it convenient for subsequent identification. Fields of bool type and json type are not supported as parameters. The red box contains the system default parameters, which are not bound to any fields and cannot be deleted, but the default values and descriptions can be modified. The specific functions of the parameters are as follows.

Parameter	Parameter Type	Parameter Description
needTotalHits	Boolean	Whether to return the total number of rows of requested data. The default is false, which does not return the total number of rows of requested data.
limit	Number	Refers to the total number of records to be obtained, with a default value of 1000, which means obtaining 1000 records.
offset	Number	Refers to the starting position of the returned records, with a default value of 0, indicating that records are obtained starting from the 1st record, with a total of limit records obtained.
orderBy	Text	The field by which the data is sorted, it is recommended to set this.
orderType	Text	Refers to the sorting method of orderBy, supporting three methods: ascending, descending, and no sorting.

• Configuration of request parameters for POST request method. Supports both request parameters and JSON parameter configuration methods. The configuration of request parameters for POST method is consistent with that for GET method, so it will not be elaborated here. When selecting JSON parameter configuration, it supports filling in JSON examples for API callers to refer to during actual calls.

4. Verify API Information. After the parameter configuration is saved, the API is successfully created with an unpublished status. Users can verify the API information on the API details page. If there are any issues, they can click Edit on the right to make modifications.

Testing and Publishing of Detailed Data API

The testing and publishing of the Detail Data API are the same as those of the Aggregate Data API. Please refer to the testing example of the Aggregate Data API for testing.

Custom Query API

Custom Query API retrieves relevant information about available Data Connections in the system through custom query statements. The API supports flexible language usage to view data content within data connections.

Create Custom Query API

Please follow the steps below to create a custom query API.

1. Create a New API. On the API Management page, click New, select Custom Query, and enter the New API page. 2. Fill in Basic Information. Fill in the API name, API path, request method, data return format, and description information as required on the page. Both POST and GET request methods are supported. 3. Configure Parameters. Introduction to each part of the parameter configuration page.

Name	Description
Data Connection	Select a data connection that the current user has access to.
Data Table	Display the schema and data tables of the selected data connection, allowing users to click to view the data of any data table.
Query Statement	Edit a custom query statement, which must conform to the syntax of the connection selected on the left.
Default Schema	When running a query statement, if all the queried data tables are under the public path, there is no need to select a default schema; If the queried data tables are in different schemas, the path of the data tables must be clearly written in the query statement; If the queried data tables are only in a single schema, you can directly specify the default schema to execute the query;
Request Parameters	Custom request parameters when querying, users must define the parameter name, type, default value, and description. Request parameters must match the parameters in the query statement.
Default Request Parameters	These are system-provided request parameters that cannot be modified or deleted. needTotalHits indicates whether to return the total number of rows of requested data. The default is false, meaning the total number of rows is not returned. limit refers to the total number of records to be obtained, with a default value of 1000, meaning 1000 records are obtained. offset refers to the starting position of the returned records, with a default value of 0, meaning records are fetched starting from the 1st record, totaling limit records. orderBy is the field based on which the data is sorted, it is recommended to set this. orderType refers to the sorting method of orderBy, supporting ascending, descending, and no sorting.
Table Data Preview	For convenience in writing query statements, users can click on any data table on the left to preview its data.
Execute	Click the Execute operation on the right, or press Shift+Enter, to view the feedback result of the query statement under the Execution Result tab.

Below is an example demonstrating the configuration process of parameters.

**4. Verify API information. **

After the parameter configuration is saved, the API creation is successful, and the status is unpublished. Users can verify the API information on the API details page. If there are any issues, they can click Edit on the right to make modifications.

Custom Query API Testing and Publishing

Custom query type API, only the default parameters are effective when checked, other parameters will complete the query according to the logic defined in the query statement, regardless of whether they are checked or not.

Register API

The registration API is an API provided by HENGSHI SENSE to encapsulate third-party APIs and offer standardized interfaces externally. The registration API supports four request methods: GET, POST, PUT, and DELETE. The parameter transmission method supports both fixed parameter passing and original parameter passing.

Create Registration API

Below is a detailed introduction on how to create, register, test, and publish an API.

1. Create a new API. On the API Management page, click New, select Register API, and enter the new API page.
2. Fill in the basic information. On the Basic Information page, fill in the API name, API path, request method, and encapsulation method as required, and add API description information.
   • The request method supports GET, POST, PUT, and DELETE.
   • The encapsulation method supports original parameter passing and fixed parameter passing. Only fixed parameter passing requires request parameter configuration. (The part in the red box in the figure).
3. Backend service configuration. On the Backend Service Configuration page, fill in the Third-party Service Protocol and Third-party Service URL as required.
4. Request parameter configuration. When the encapsulation method is fixed parameters, request parameter configuration is required. Add parameters in Query parameters and request headers as needed. Additionally, POST requests support JSON for parameter configuration, where examples can be filled in for reference by callers.

   Tip

   When adding parameters in the request header, Content-Type is only allowed to contain the tag value in application/json format, and other format values are not supported.

5. Review API information. After the parameter configuration is saved, the API creation is successful, and the status is unpublished. Users can review the API information on the API details page. If there are any issues, they can click Edit on the right to make modifications.

Register API Publishing and Testing

Registration API differs from other APIs, as it includes both Query parameters and request headers in the request parameters. When sending an API request, it is necessary to pay attention to both parts of the parameters.

Publish/Republish/Unpublish

The created and tested API can be published to the API service by selecting …Menu -> Publish.

In the published state of the API, it supports starting/pausing API operations based on data update status to ensure that the API fetches the latest data. When the API service is started, the corresponding API service status is Running, and when the service is paused, the API service status is Maintenance.

After the API is published, editing operations are still supported on the API management page. The published state and editing state of the API do not affect each other. Until the user selects …Menu -> Republish to publish the API again, the results of the re-editing will overwrite the published state of the API. Users with permission to call the API will execute the query with the new query conditions when calling the API.

When the API is not authorized to the API group, users can choose …Menu -> Unpublish to unpublish it, no longer providing query services. If the API has been authorized to certain API groups, you must first cancel the authorization before you can perform the Unpublish operation.

Editing

After the API is created, you can click …Menu -> Edit or the Edit button on the details page to modify the relevant information.

• When the API is in the Unpublished state, modifications made after clicking the save button will take effect immediately.
• When the API is in the Published state, modifications made after clicking the save button will not take effect immediately. The API needs to be Republished for the changes to take effect.

API Authorization

The Published API can be authorized to an API group by selecting …Menu -> Authorize, and then the API group will handle unified authentication and authorization. Authorization supports time-based and count-based authorization, tailored to the needs of different API groups.

After authorization, users can select …Menu -> Revoke Authorization to revoke their authorization for the API group. Once authorization is revoked, the API group will no longer have permission to call the current API.

Tip

The unpublished API is not allowed to perform authorization operations because it does not provide API services.

API Monitoring

Click API Monitoring on the API Details page to view the current API's call status.

Rate Limiting

The system supports setting limits on the frequency of API calls. Click Rate Limit to display the rate limiting information related to the API, which can be modified through editing.

• API traffic limit refers to the maximum traffic allowed for accessing the API. The default value is the single API default traffic limit control set by the system.

• API group traffic limit refers to the restriction on the access limit of the API group to a single API, and all API groups bound to this API are subject to this traffic limit.

API Circuit Breaker

In API management, support for setting API circuit breakers is provided. Before setting a circuit breaker, please read the Circuit Breaker Policy to understand the use cases for API circuit breaking.

On the API Management -> API Policy page, click the edit button to open the API Circuit Breaker Policy page. After checking the Enable button, you can set the circuit breaker rules. For the meanings and functions of the circuit breaker parameters, please refer to Circuit Breaker Parameter Description.

Tip

1. This API circuit breaker rule only applies to this API and does not affect other APIs.
2. After setting this API circuit breaker rule, modifications to the Global API Circuit Breaker Rule will not affect the circuit breaker rule of this API.

Delete

Users can select …Menu -> Delete to delete a specific API. The Delete button on the API details page can also be used to delete the API.

• Published APIs cannot be deleted as they are currently in service. To delete, you must select …Menu -> Unpublish first.
• Unpublished APIs can be deleted normally.

API Group

Group APIs from the same business domain together, and provide users with API invocation authorization by group. Members within the group use the same authentication information, so when members within the group access APIs within the group, they can obtain the same data, aligning with the scenario of consistent data within the same business domain.

API Group List

Click API Service -> API Group to open the API Group list, displaying all API Groups that the current user has access to, including those created by themselves and those authorized to them.

This page provides operations for creating, viewing, editing, and deleting API groups.

Create API Group

Users with the API Management role can create API groups. Click API Services -> API Groups -> + New API Group to open the new group popup. Enter the API group name and description, and the API group will be created.

View API Groups

API group creation is complete, and the page refreshes to display its details page. Users with permissions can also click API Services -> API Groups, select a specific API group to open its details page.

The page displays the basic information, authentication information, and bound API list of the API group. The owner and administrators of the API group can also perform a series of management operations such as editing, authorization, binding APIs, and deletion. Users cannot perform the above management operations.

Member Management

API group owners can click API Services -> API Groups -> API Group Details Page -> Member Management to add members who need to access the business domain data together into this group. Among them, managers can perform all management operations including deletion on the API group, while users can only view the information of the API group to obtain the authentication information for accessing the group's APIs and the necessary URL information for calling each API.

View API Group's API Details

API group members can click API Service -> API Group -> API Group Details Page -> Select API to open the API details page within the API group, Here, API group members can test the API, view the API's URL information, and thus combine it with the API group's authentication information to complete the API call.

Supports unbinding APIs. After unbinding, the API group will not be able to call this API.

Request API

The above describes the creation of an API and binding it to the corresponding group. Below, we will introduce how to request the API.

Apply for Token

Each API must be bound to an API group to be accessed. Within the API group, you can see the Key and Secret. Using this information, you can obtain a token. The URL to obtain the token is http://{host}/api/oauth2/server/tokens?grant_type=client_credentials&client_id={key}&client_secret={secret}, where host is the host address.

When the host is https://develop.hengshi.org, the URL formed using the Key and Secret from the API group in the image above is https://develop.hengshi.org/api/oauth2/server/tokens?grant_type=client_credentials&client_id=b4c6ad9890414817838ed20d0b2de0e2&client_secret=b32a47dac80c471b95b330865f405063 to obtain the access_token on Apifox. (Note: Apifox extracts the parameters from the URL)

Use token to request API data

After obtaining the token, you can request the API. The URL for the API request is http://{host}/{path}?access_token={token}, where host is the host address and path is the path of the API.

When the host is https://develop.hengshi.org and the path is /api/open/getcustomer11, the URL for accessing the API is https://develop.hengshi.org/api/open/getcustomer11?access_token=2ccfff27-229c-4dc4-804b-c75983150434. The data obtained by accessing the API on Apifox is shown in the figure below. (Note: Apifox extracts the parameters from the URL)

When making an API request with parameters, the URL format is http://{host}/{path}?access_token={token}&{param}=....&hsConditionFieldOp={"{param}":"{op}"....}&hsConditionConnector=and/or, where the parameter values and operators need to be reflected in the URL. In the example above, to view information values where id>90, the URL would be https://develop.hengshi.org/api/open/getcustomer11?access_token=2ccfff27-229c-4dc4-804b-c75983150434&id=90&hsConditionFieldOp={"{id}":"{>}"}. Additionally, the value of the connector hsConditionFieldOp needs to be urlEncoded when accessing the URL, so the final URL used would be https://develop.hengshi.org/api/open/getcustomer11?access_token=2ccfff27-229c-4dc4-804b-c75983150434&id=90&hsConditionFieldOp=%7B%22id%22%3A%22%3E%22%7D%0A

Tip

1. The parameter usage format for the custom query API is {{##apiParam}}.
2. The available configuration parameters for the API request are hsConditionFieldOp (not available for custom query API): {"{param}":"{op}"....}, which can specify the operator {op} corresponding to the custom parameter {param}, such as: {"director":"!="}, equivalent to where director!=xxx, hsConditionConnector (only available for detail API): and/or, which can specify the connector between parameters as and or or.

API Monitoring

Users can also view the overall situation of all API services through the API Monitoring tab.

API Policy

Flow Control Policy

API rate limiting strategy refers to the restriction of API traffic, limiting both the overall API traffic and individual API traffic to prevent excessive API scheduling from affecting the normal operation of the system and to protect system resources.

In the flow control policy, you can set global API traffic limits and default traffic limits for individual APIs.

• Global API traffic limit refers to controlling the total sum of API traffic across the entire system, ensuring that the total does not exceed the set global API traffic limit. API requests exceeding this limit will be denied access.

• The default traffic limit for a single API sets the maximum allowable traffic for an individual API within the system, applying to all APIs.

API Traffic Limits

Flow control policies are designed to limit API traffic from a global perspective. Each API can independently control its own API traffic. For detailed instructions, please refer to Rate Limiting.

API Traffic Control Instructions

Each API is controlled by three traffic indicators: Global API Traffic Limit, API Traffic Limit, and API Group Traffic Limit. The relationship between the three is

1. The API traffic limit value cannot be greater than the global API traffic limit value.
2. The API group traffic limit value cannot be greater than the API traffic limit value.

The following situations may result in API access being denied.

1. If an API group does not reach the traffic limit for API access frequency, but the access frequency of that API reaches the traffic limit, then the API group cannot continue to access that API.
2. If the access frequency of an API does not reach the traffic limit, but the sum of all APIs reaches the traffic limit, then that API cannot continue to access.

Circuit Breaker Strategy

During the API invocation process, due to environmental factors, requests may fail. After receiving a failure message, the requester may continuously send requests, causing the system to frequently process request messages. When multiple APIs in the system exhibit similar situations, the system may handle a large number of request messages in a short period, potentially leading to system crashes in extreme cases. To address this, an API circuit breaker function has been introduced, allowing requests to fail quickly within a certain period, thereby avoiding system impact and protecting system stability.

Users can set up unified settings for APIs within the system through Global API Circuit Breaker, or set up circuit breaker settings for a specific API through Single API Circuit Breaker. Below is a detailed introduction to API circuit breaker rules.

Circuit Breaker Rules

API circuit breaking enabled, within the statistical duration, when the number of requests exceeds the minimum request count, and the proportion of abnormal requests exceeds the circuit breaking threshold, all requests will fail quickly within the circuit breaking duration. After the circuit breaking duration, attempts will be made to restore the requests.

The information required for circuit breaking is shown in the table below.

Parameter Name	Parameter Description
Statistical Window Duration	Statistics on the number of API requests within this window time, in seconds or minutes.
Minimum Request Count	The number of requests that trigger the circuit breaker. The circuit breaker will not be activated if the number of requests within the statistical window duration is less than the minimum request count.
Circuit Breaker Threshold	The abnormal ratio that triggers the circuit breaker.
Circuit Breaker Duration	The duration of the circuit breaker, in seconds. API requests will fail quickly during this time.

When the API is in a circuit breaker state, all API requests will fail quickly. After the circuit breaker duration, it will attempt to resume API request processing. If the API request processing is successful, the circuit breaker will end; otherwise, it will return to the circuit breaker state.

Global API Circuit Breaker Settings

Global API Circuit Breaker Settings refer to the overall circuit breaker rule settings for APIs, which take effect for all APIs after the rules are set. Set the circuit breaker rules in API Services -> API Policies -> Circuit Breaker Policies, and these rules apply to all APIs.

Single API Circuit Breaker Settings

Single API Circuit Breaker Setting refers to the setting of circuit breaker rules for a specific API. After the rules are set, this API is not restricted by the global API circuit breaker rules. For specific settings, please refer to API Circuit Breaker.

Circuit Breaker Exception Notification

When the API is in a circuit breaker state, it will cause the request for that API to fail quickly. After the circuit breaker duration is reached, the next API request will attempt to recover. If the request fails, the circuit breaker will be activated again. If multiple consecutive attempts to recover the API fail, it can be considered that the API is in an abnormal state, and an email will be sent for abnormal reminder.

Exception alerts can be set to specify the number of consecutive recovery failures and email recipients. When the number of consecutive recovery failures reaches the set value, an email notification will be sent to the corresponding users.

API Import and Export

Users may deploy many environments in actual use, each requiring the creation of numerous API services for the same business processes, leading to a lot of repetitive work. To address this, the API import and export feature was introduced, allowing users to easily import APIs from one environment into another, saving them from redundant development efforts. Below is a detailed introduction to the API import and export process.

API Export

API export is the process of exporting APIs in JSON format, facilitating import into other environments. Please follow the instructions below to complete the API export.

1. Click the red box in the API Management to enter the batch operation page.
2. In the upper right corner of the batch operation page, you can quickly filter APIs by Search, API Type, and Publishing Status, then select the APIs you need to export from the filtered results, with full selection supported.
3. Click Export, and the selected APIs will be exported in json format.

API Import

API import involves importing the exported API's JSON file into the system. Please follow the steps below to complete the API import.

1. In API Management, click New API -> Import Template, and then select the API template file.
2. After the template file is imported, three import results will be displayed: Import Successful, Import Failed, and Imported, Configuration Exception.
3. APIs that prompt Import Successful are in an unpublished state and need to be tested before being published for use.
4. APIs that prompt Import Failed may be due to conflicts in the API path or incomplete information. Please modify and re-import.
5. APIs that prompt Imported, Configuration Exception may have some configuration issues that need to be corrected. As shown in the figure, the API, after being imported, shows a configuration exception because the original chart or dataset does not exist, requiring reconfiguration of the exception items. After modification, the API is in an unpublished state and needs to be tested before being published.

Tip

API Import avoids users from repeatedly creating APIs, but the imported API is in an unpublished state and requires users to retest and then publish it for use.

Execute Query

Members of the API group can all call the API via the URL within the group using unified authentication information. The steps are as follows:

1. Click API Service -> API Group -> API Group Details Page to open the API Group Details Page and obtain the API Group's authentication information.
2. Generate a token using the API Group's key and secret.
3. In the API Group Details Page from step 1, click to select the API you are ready to call, open the API Details Page, and copy the URL address.
4. Append the token from step 2 to the API's URL address. If you need to define request parameters, also append them to the URL address.
5. Complete the call.

Please note

The authentication information of the API group cannot be used to call Open API interfaces within the HENGSHI SENSE system, it can only be used to call APIs within the API group.