Skip to main content

Read and Write Worksheet Data via API


HAP provides APIs that allow developers to integrate worksheets with external systems. You can use these APIs to write data from external systems to worksheets or retrieve existing worksheet data.

Example Use Case​

Suppose you have an Order Management app with an Orders worksheet that tracks both online and offline orders. You also use an online sales system to manage orders placed through your website.

Whenever a customer places an online order, you can use the Worksheet API to automatically create a corresponding record in the Orders worksheet. This eliminates manual data entry, saves time, and reduces the risk of errors.

API Documentation​

App administrators can open the API documentation to view all available APIs for the current app.

App Authorization​

HAP uses token-based authentication. The AppKey and SecretKey are provided in the app's API documentation. Super Admins can also regenerate these credentials.

Field and Control Type Reference​

  • Field ID: A system-generated identifier for a field that cannot be changed. When writing data through an API, use the field ID to identify the target field.

  • Field Name: The name assigned to the field by the app administrator.

  • Type: The control type selected for the field.

  • Control Type ID: The numeric identifier of the control type, commonly used in API requests. Different control types may support different filtering methods.

  • Description: Information about the field, such as its data type, sample values, and whether it supports writing data.

  • Worksheet and Field Aliases: Worksheet IDs and field IDs are long strings that can be difficult to remember or enter. You can assign aliases to worksheets and fields and use these aliases in API requests instead of their IDs.

API for Adding Records​

HAP provides more than 10 APIs to support various data operations.

The following example demonstrates how to create a new record in a worksheet using an API.

Request Guidelines​

  • API Endpoint:

    https://api.mingdao.com/v2/open/worksheet/addRow

  • Request Parameters:

    You can reuse the values provided on the right side of the API documentation for parameters such as appkey, sign, worksheetid, controls, and controlId.

    Parameter names are automatically generated based on the current worksheet and should not be changed. When testing the API, you only need to modify the parameter values as needed.

Sample Request (Ready to Copy)

{
"appKey": "15d5b427b4bbf1b6",
"sign": "ZDRjZDEzM2Q3YzUzMGI1ZDhjOWNhOWQ2MzFiZDkxNDY1NmYyZjBiYjE1YzYzZGMxNGU0MmNjZDA2NjJmYjViNA==",
"worksheetId": "655c79654120176fa4758593",
"controls": [
{
"controlId": "6426808e315e39d1e4dae83e",
"value": "This is a test"
},
{
"controlId": "5e0a02642134520001e19345",
"value": "666.66"
}
],
"triggerWorkflow": true
}

Response Parameters and Sample Response

{
"data": "75f221fb-d645-4010-92cb-acced0c73cea",
"success": true
}

Error Codes

ErrorCodeDescription
0Failed
1Success
10001Missing required parameters
10002Invalid parameter value
10005Insufficient permissions for data operations
10007Data does not exist
10101Request token does not exist
10102Invalid signature
99999Data operation error

Test the API​

In this example, we'll use an online API testing tool to simulate writing data from an external system to a worksheet.

We recommend https://hoppscotch.io, but you can use any API testing tool.

  1. Paste the API endpoint into the request URL field.
  2. Select POST as the request method.
  3. Select Body for the request payload.
  4. Set Content-Type to application/json.
  5. Paste the sample request code from the API documentation into the request body editor.
  6. Click Send to submit the request.
  7. Check the response displayed below. If it contains "success": true, the record was created successfully. Refresh the worksheet to view the new record. Its creator will be displayed as API.

When testing APIs, you may need specific parameter values, such as a View ID or Record ID (rowId).

Record ID (rowId)​

Open the record details page, click Copy ID in the More menu to obtain the record ID.

View ID​

A View ID is required when retrieving records from a specific view.

How to Find the View ID:

In the app's API documentation, go to App Authorization > Worksheet > Target Worksheet > View Information Table to find the View ID.

Was this document helpful?