How to read/write data to worksheets via API
HAP provides API interfaces for users with development capabilities so that they can write external data to a worksheet or read data from a worksheet.
Use Case
There is an Order Management worksheet created in your application to manage both online and offline orders. There is another sales system, and whenever a customer mades an order online, it writes a new order record directly to the Order Management worksheet via the API of the worksheet.
API Description
Application Admins click [API Documentation] to view all the APIs in the application.
Authorization Description
HAP takes token-based authentication, so the AppKey and SecretKey should be obtained by the system Super Admin, or they can be regenerated.
Field and Control Type
Field ID: The ID automatically generated by the system for the field, which can not be modified, and the field ID is necessary to represent the field when writing data via API.
Field Name: The name set by Application Admin for the field.
Type: Control type of the field.
Control Number: The number of the control used, typically used when passing parameters. The filtering may vary for different types of controls.
Description: Description of use of the field.
Worksheet Alias and Field Alias: Since the worksheet ID and field ID are a long string of characters that are not easy to remember or write, you can set aliases for the worksheets and fields for passing parameters.
Interface for Adding Records
There are more than 10 interfaces provided in the application for different application scenarios. Here is an example of creating a new record, i.e., adding a new record to the worksheet through the API.
Rules
- Address of API request: https://api.mingdao.com/v2/open/worksheet/addRow
- For the parameters appkey, sign, worksheetid, controls and controlId, you can use the values already provided on the right. The parameter names do not need to be modified, as they are automatically generated based on the worksheet, and only the parameter values need to be modified when testing.
Example of Request (can copy and use it)
{
"appKey": "15d5b427b4bbf1b6",
"sign": "ZDRjZDEzM2Q3YzUzMGI1ZDhjOWNhOWQ2MzFiZDkxNDY1NmYyZjBiYjE1YzYzZGMxNGU0MmNjZDA2NjJmYjViNA==",
"worksheetId": "655c79654120176fa4758593",
"controls": [
{
"controlId": "6426808e315e39d1e4dae83e",
"value": "This is a test"
},
{
"controlId": "5e0a02642134520001e19345",
"value": "666.66"
}
],
"triggerWorkflow": true
}
Example of Response Parameters and Returned Data
{
"data": "75f221fb-d645-4010-92cb-acced0c73cea",
"success": true
}
Possible Error
| ErrorCode | Description |
|---|---|
| 0 | Fail |
| 1 | Success |
| 10001 | Missing parameters |
| 10002 | Incorrect parameter values |
| 10005 | No permission to operate |
| 10007 | Data not existing |
| 10101 | Request token not existing |
| 10102 | Illegal signature |
| 99999 | Abnormal data operation |
Online Test
Here we are simulating the writing of external data through a simple online API test.
Online API Test: https://hoppscotch.io. You can also use other API testing tools.
- Paste the API request address into the input box
- Select Post
- Select Body
- Select "application/json" for Content Type
- Paste the example request code above into the edit box
- Click Send
- If it is success": true , it means it has been written successfully. Refresh the worksheet to check the new data, created by API.
Ways to get the relevant parameters
When testing, you can first get a fixed parameter value, such as the view ID and row record ID (rowId).
Row Record ID（rowId）
Go to the worksheet and open the detail page of the target record.
The content between rows/ and ? in the link is the record id.
Record ID obtained in the screenshot:
4c76dc8d-b8b3-4695-b776-e261dceb9ed3
View ID
The view ID is required to get the list of records.
Have questions about this article？ Send us feedback