Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
The REST Table API allows you to perform the create, read, update, and delete (CRUD) operations on the existing tables.
CRUD requests to the Table API are executed according to the ACL rules.
Table API URL format:
Name | Value |
---|---|
Default URL | /rest/v1 |
/rest/v1/table/ |
This method allows inserting one record in the defined table. It does not support multiple records insertion.
Authorization
Two types of Table API request authorization are supported:
- Basic Auth – authentication involves sending a verified username and password with the request.
- Bearer Token – authentication with an access key. The token is a text string, included in the request header.
Image Added
CREATE operations
Use the POST method to insert one record into the defined table. It does not support insertion of multiple records.
Example:
Code Block |
---|
POST |
Parameters
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
...
<column_name> => <column_value>
...
} |
READ operations
GET/rest/v1/table/{ |
tableName} |
This method returns multiple records for the essence table.
Body parameter
You can specify as many columns and their values as you need.
Parameter | Value |
---|---|
column_name | column_value |
You can use the following parameters with this method:
GET /rest/v1/table/{essence}/{sys_id}
This method retrieves one record from the essence table.
UPDATE operations
PATCHPUT /rest/v1/table/{essence}/{sys_id}
This method updates the specified record with the request body in the essence table.
Parameter | Description |
---|---|
sysparm_display_value | An operation method for data retrieval. It may return both types of values.
Default value: 0. |
sysparm_exclude_reference_link | A flag indicating whether to exclude the Table API links ( |
/rest/v1/table/ |
This method updates the specified record with the request body in the essence table.
Parameters
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
...
<column_name> => <column_value>
...
} |
DELETE operations
ParametersDELETE /rest/v1/table/{essence}/{sys_id}
Deletes the specified record with the request body from the essence table.
Data retrieval operation method. Also, may return both types of values.
- TRUE: returns field display values.
- FALSE: returns actual values.
Default: FALSE
Valid values:
- TRUE: exclude Table API links for reference fields.
- FALSE: include Table API links for reference fields.
Default: FALSE
) for reference fields. Valid values:
Default value: 0. | |
sysparm_fields | A comma-separated list of fields to return to the response. Value example: number,caller. |
sysparm_view | The response contains the fields of the form view defined by this parameter. Note that it can be overridden by sysparm_fields. Default value: Default. |
Note |
---|
You need to use raw JSON type of Body instead of form-data. |
Example:
Image Added
Section | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The maximum number of results returned per page.
This parameter is equal to the self::CRUD_API_LIMIT_RECORDS.
Default = 20 (for GET-queries).
Page number to offset records.
Default = 1.
Code Examples
Image Removed
Code Block | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{
|
READ operations
Read operations in SimpleOne are limited to the GET method. Depending on whether you need to retrieve a single record or some of them, follow the examples below:
To retrieve a single record from the specified table:
Code Block |
---|
GET /rest/v1/table/{tableName}/{sys_id} |
To retrieve multiple record query from the specified table:
Code Block |
---|
GET /rest/v1/table/{tableName} |
You can use the following parameters with this method:
Parameter | Description |
---|---|
sysparm_query | An encoded query string used to filter the results. Value example: active=1. |
sysparm_display_value | An operation method for data retrieval. It may return both types of values.
Default value: 0. |
sysparm_exclude_reference_link | A flag indicating whether to exclude Table API links (/rest/v1/table/ ) for reference fields.Valid values:
Default value: 0. |
sysparm_fields | A comma-separated list of fields to return to the response. Value example: number,caller. |
sysparm_view | The response contains the fields of the form view defined by this parameter. Note that it can be overridden by sysparm_fields. Default value: Default. |
sysparm_limit | The maximum number of results returned by query. Default value: 20. |
sysparm_page | Define the page number to start reading from. For example, if sysparm_limit is set to 40, and you set sysparm_page to 2, the response will include records from 21 to 60. Default value: 1. |
Note |
---|
Use raw JSON type of Body instead of form-data. |
Image Added
Section | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"status": "OK",
"data": [
{
"sys_id": 156016554400838540,
"parent_id": null,
"sys_updated_at": "2019-06-10 11:19:04",
"impact": null,
"number": "TSK002930",
"sys_created_at": "2019-06-10 11:19:04",
"assigned_user": {
"value": "155964310500000018",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"sys_updated_by": {
"value": "155964310500000018",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"active": null,
"opened_at": null,
"contact": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"sys_created_by": {
"value": "155964310500000018",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"closed_at": null,
"display_name": "TSK002930 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": 0,
"burned_points": null,
"caller": null,
"state": 7,
"description": null,
"subject": "1"
}
]
}
|
Image Removed
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"status": "OK",
"data": [
{
"sys_id": 155981791201907166,
"parent_id": null,
"sys_updated_at": "2019-06-06 10:45:13",
"impact": null,
"number": "TSK002918",
"sys_created_at": "2019-06-06 10:45:13",
"assigned_user": null,
"sys_updated_by": {
"value": "155964310500000018",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"active": null,
"opened_at": null,
"contact": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"sys_created_by": {
"value": "155964310500000018",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"closed_at": null,
"display_name": "TSK002918 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": 0,
"burned_points": null,
"caller": null,
"state": 7,
"description": null,
"subject": "1"
}
]
}
|
Image Removed
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"status": "OK",
"data": [
{
"sys_id": 155981791201907166,
"parent_id": null,
"sys_updated_at": "2019-06-06 10:45:13",
"impact": null,
"number": "TSK002918",
"sys_created_at": "2019-06-06 10:45:13",
"assigned_user": null,
"sys_updated_by": "155964310500000018",
"active": null,
"opened_at": null,
"contact": "",
"sys_created_by": "155964310500000018",
"closed_at": null,
"display_name": "TSK002918 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": "",
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": 0,
"burned_points": null,
"caller": null,
"state": 7,
"description": null,
"subject": "1"
}
]
}
|
Image Removed
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"status": "OK",
"data": [
{
"sys_id": 156016554400838540,
"parent_id": null,
"sys_updated_at": "2019-06-10 11:19:04",
"impact": null,
"number": "TSK002930",
"sys_created_at": "2019-06-10 11:19:04",
"assigned_user": {
"value": "Jane Doe",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"sys_updated_by": {
"value": "Jane Doe",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"active": null,
"opened_at": null,
"contact": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"sys_created_by": {
"value": "Jane Doe",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"closed_at": null,
"display_name": "TSK002930 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": 0,
"burned_points": null,
"caller": null,
"state": "Completed",
"description": null,
"subject": "1"
},
{
"sys_id": 155964310500002012,
"parent_id": null,
"sys_updated_at": "2019-06-18 15:28:32",
"impact": null,
"number": "TSK002836",
"sys_created_at": "2019-02-19 14:30:19",
"assigned_user": null,
"sys_updated_by": {
"value": "Jane Doe",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"active": true,
"opened_at": null,
"contact": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"sys_created_by": {
"value": "John Doe",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000026"
},
"closed_at": null,
"display_name": "TSK002836 ",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": null,
"assignment_group": null,
"watcher_list": null,
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Changed",
"total_points": null,
"burned_points": null,
"caller": null,
"state": "Scheduled",
"description": "",
"subject": ""
}
]
}
|
Image Removed
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"status": "OK",
"data": [
{
"sys_id": 155981791201907166,
"parent_id": null,
"sys_updated_at": "2019-06-06 10:45:13",
"impact": null,
"number": "TSK002918",
"sys_created_at": "2019-06-06 10:45:13",
"assigned_user": null,
"sys_updated_by": "Jane Doe",
"active": null,
"opened_at": null,
"contact": "",
"sys_created_by": "Jane Doe",
"closed_at": null,
"display_name": "TSK002918 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": "",
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": 0,
"burned_points": null,
"caller": null,
"state": "Completed",
"description": null,
"subject": "1"
},
{
"sys_id": 155983188102317352,
"parent_id": null,
"sys_updated_at": "2019-06-06 14:38:01",
"impact": null,
"number": "TSK002926",
"sys_created_at": "2019-06-06 14:38:01",
"assigned_user": null,
"sys_updated_by": "Jane Doe",
"active": null,
"opened_at": null,
"contact": "",
"sys_created_by": "Jane Doe",
"closed_at": null,
"display_name": "TSK002926 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": "",
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": 0,
"burned_points": null,
"caller": null,
"state": "Completed",
"description": null,
"subject": "1"
}
]
}
|
CREATE operations
Image Removed
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"status": "OK",
"data": [
{
"sys_id": 156741210205635452,
"parent_id": null,
"sys_updated_at": {
"expression": "NOW()",
"params": []
},
"impact": null,
"number": "TSK00031",
"sys_created_at": {
"expression": "NOW()",
"params": []
},
"assigned_user": null,
"sys_updated_by": {
"value": "155964310500000001",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000001"
},
"active": null,
"opened_at": null,
"contact": null,
"sys_created_by": {
"value": "155964310500000001",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000001"
},
"closed_at": null,
"display_name": "TSK00031 test",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": null,
"assignment_group": null,
"watcher_list": null,
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Open",
"total_points": null,
"burned_points": null,
"caller": 156636690504223270,
"state": null,
"description": null,
"subject": "test"
}
]
} |
UPDATE operations
Image Removed
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"status": "OK",
"data": [
{
"sys_id": 155981791201907166,
"parent_id": null,
"sys_updated_at": {
"expression": "NOW()",
"params": []
},
"impact": null,
"number": "TSK002918",
"sys_created_at": "2019-06-06 10:45:13",
"assigned_user": null,
"sys_updated_by": {
"value": "155964310500000001",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000001"
},
"active": null,
"opened_at": null,
"contact": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"sys_created_by": {
"value": "155964310500000018",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000018"
},
"closed_at": null,
"display_name": "TSK002918 1",
"steps_to_reproduce": null,
"priority": null,
"screenshot": null,
"attention_required": false,
"assignment_group": null,
"watcher_list": {
"value": "",
"link": "https://your-instance-address.com/rest/v1/table/user/"
},
"company": null,
"work_notes": null,
"additional_comments": null,
"closed_by": null,
"opened_by": null,
"due_date": null,
"sys_db_table_id": 155964310500000025,
"urgency": null,
"policy": "Changed",
"total_points": 0,
"burned_points": null,
"caller": 156636690504223270,
"state": 7,
"description": null,
"subject": "1"
}
]
}
|
Image Removed
|
UPDATE operations
There are two methods available for the UPDATE operations: PUT and PATCH. PUT contains new versions of records. Whereas in PATCH, nested objects contain a set of instructions that describe how records on the origin server should be updated to create new versions.
Body parameter
You can specify as many columns and their values as you need.
Parameter | Value |
---|---|
column_name | column_value |
Note |
---|
Use raw JSON type of Body instead of form-data. |
You can use the following parameters for the PUT and PATCH methods:
Parameter | Description |
---|---|
sysparm_display_value | An operation method for data retrieval. It may return both types of values.
Default value: 0. |
sysparm_exclude_reference_link | A flag indicating whether to exclude Table API links (/rest/v1/table/ ) for reference fields.Valid values:
Default value: 0. |
sysparm_fields | A comma-separated list of fields to return to the response. Value example: number,caller. |
sysparm_view | The response contains the fields of the form view defined by this parameter. Note that it can be overridden by sysparm_fields. Default value: Default. |
PUT
Use it to update records in the specified table using the values defined in the request body.
Example:
Code Block | ||
---|---|---|
| ||
PUT /rest/v1/table/{tableName}/{sys_id} |
PATCH
Use it to partially update records. This method updates a specified record with the request body in the specified table.
Example:
Code Block |
---|
PATCH /rest/v1/table/{tableName}/{sys_id} |
Example:
Image Added
Section | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Code Block | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{
"status": "OK",
"data": [
{
"sys_id": 155983188102317352,
"parent_id": null,
"sys_updated_at": {
"expression": "NOW()",
"params": []
},
"impact": null,
"number": "TSK002926",
"sys_created_at": "2019-06-06 14:38:01",
"assigned_user": null,
"sys_updated_by": {
"value": "155964310500000001",
"link": "https://your-instance-address.com/rest/v1/table/user/155964310500000001"
},
"active": null,
|
DELETE operations
|
DELETE operations
Use this method to delete a specified record with the request body from the specified table.
Example:
Code Block |
---|
DELETE /rest/v1/table/{tableName}/{sys_id} |
There are two possible responses:
- When a record was successfully deleted.
- When an error occurred.
Example:
Image Added
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
DELETE /rest/v1/table/sys_filter/166039918402151705 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu |
Success response
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "status": "OK", "data": { "description": "Records successfully deleted." } } |
Image RemovedError response
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"status": "ERROR",
"error_type": "SERVER",
"errors": [
{
"message": "You have no access to delete this records."
}
]
}
|
Authorization
Table of Contents | ||||
---|---|---|---|---|
|