You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 44 Next »
The REST API allows you to perform create, read, update, and delete (CRUD) operations on existing tables.
URL format:
Name | Value |
---|---|
Default URL | /rest/v1 |
Authorization
In SimpeOne, three types of authorization are supported:
- No Auth – request does not require authorization.
- 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.
CREATE operations
POST /rest/v1/table/{tableName}
This method allows for inserting one record in the defined table. It does not support multiple records insertion.
Parameters
Name | Description |
---|---|
sysparm_display_value | Data retrieval operation method. Also, may return both types of values.
Default value: false. |
sysparm_fields | A comma-separated list of fields to return to the response. Value example: username,email. |
sysparm_view | Render the response according to the specified UI view (overridden by sysparm_fields). Value example: SP. |
Body parameter
Parameter | Value |
---|---|
column_name | column_value |
You need to use raw JSON type of Body instead of form-data.
POST /rest/v1/table/dashboard HTTP/1.1 Host: your-instance.example.ru Content-Type: application/json Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6 Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc Content-Length: 141 { "name": "My Dashboard", "description":"Some description", "refresh_time": "300" }
{ "status": "OK", "data": [ { "sys_id": "165166624317136512", "application_id": { "value": "155931135900000002", "link": "http://your-instance.example.ru/rest/v1/table/sys_application/155931135900000002" }, "description": "Some description", "name": "My Dashboard", "policy": "Open", "refresh_time": "300", "sys_created_at": "2022-05-04 12:10:43", "sys_created_by": { "value": "155931135900000001", "link": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001" }, "sys_updated_at": "2022-05-04 12:10:43", "sys_updated_by": { "value": "155931135900000001", "link": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001" } } ] }
READ operations
GET /rest/v1/table/{tableName}This method returns multiple records for thespecified table.
GET /rest/v1/table/{tableName}/{sys_id}
This method retrieves one record from the specified table.
Parameters
Name | Description |
---|---|
sysparm_query | An encoded query string used to filter the results. Value example: last_nameENDSWITHov. |
sysparm_display_value | Data retrieval operation method. Also, may return both types of values.
Default value: false. |
sysparm_exclude_reference_link | Flag that indicates whether to exclude Table API links for reference fields. Valid values:
Default value: false. |
sysparm_fields | A comma-separated list of fields to return to the response. Value example: username,email. |
sysparm_view | Render the response according to the specified UI view (overridden by sysparm_fields). Value example: SP. |
sysparm_limit | The maximum number of results returned per page. Default value: 20 (for GET-queries). |
sysparm_page | Page number to offset records. Default value: 1. |
You need to use raw JSON type of Body instead of form-data.
GET /rest/v1/table/itsm_change_request HTTP/1.1 Host: your-instance.example.ru Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6 Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc
{ "status": "OK", "data": [ { "sys_id": "156951264211094636", "application_id": { "value": "155931135900000002", "link": "http://your-instance.example.ru/rest/v1/table/sys_application/155931135900000002" }, "description": "", "elevated_privilege": false, "name": "impersonator", "policy": "Protected", "sys_created_at": "2019-09-30 00:00:00", "sys_created_by": { "value": "155931135900000001", "link": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001" }, "sys_updated_at": "2019-12-17 15:32:15", "sys_updated_by": { "value": "155931135900000001", "link": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001" } } ] }
UPDATE operations
There are two methods available for UPDATE operations:
- PUT creates records or updates records with values defined in the request body.
- PATCH is used to partially update records.
In other words, in PATCH, nested objects contain a set of instructions that describe how records on the origin server should be updated to create new versions. And PUT contains new versions of records.
PUT /rest/v1/table/{tableName}/{sys_id}
This method updates the specified record with the request body in the specified table.
PATCH /rest/v1/table/{tableName}/{sys_id}
This method updates the specified record with the request body in the specified table.
Parameters
Name | Description |
---|---|
sysparm_display_value | Data retrieval operation method. Also, may return both types of values.
Default value: false. |
sysparm_fields | A comma-separated list of fields to return to the response. Value example: username,email. |
sysparm_view | Render the response according to the specified UI view (overridden by sysparm_fields). Value example: SP. |
Body parameter
Parameter | Value |
---|---|
column_name | column_value |
You need to use raw JSON type of Body instead of form-data.
PUT /rest/v1/table/user/164926188012940692 HTTP/1.1 Host: your-instance.example.ru Content-Type: application/json Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6 Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc Content-Length: 26 { "username": "john.doe" }
{ "status": "OK", "data": [ { "sys_id": "164926188012940692", "active": true, "auth_key": null, "company": null, "date_format_id": { "value": "159836398504170273", "link": "http://your-instance.example.ru/rest/v1/table/sys_date_format/159836398504170273" }, "department": null, "display_name": "John Doe", "email": "johndoe@mail.com", "first_name": "John", "language_id": { "value": "156628684306200767", "link": "http://your-instance.example.ru/rest/v1/table/sys_language/156628684306200767" }, "last_name": "Doe", "ldap_server_id": null, "location": null, "locked_out": false, "log_out_on_all_devices": false, "photo_id": null, "primary_group": null, "source": "", "sys_created_at": "2022-04-06 16:18:00", "sys_created_by": { "value": "155931135900000001", "link": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001" }, "sys_db_table_id": "155931135900000084", "sys_updated_at": "2022-04-29 11:25:53", "sys_updated_by": { "value": "155931135900000001", "link": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001" }, "timezone_id": { "value": "156076775207685877", "link": "http://your-instance.example.ru/rest/v1/table/sys_timezone/156076775207685877" }, "username": "john.doe" } ] }
DELETE operations
DELETE /rest/v1/table/{tableName}/{sys_id}
Deletes the specified record with the request body from the specified table.
You can receive one of two possible responses:
- When the record was successfully deleted.
- When an error occurred.
You need to use raw JSON type of Body instead of form-data.
DELETE /rest/v1/table/dashboard/165476748114102626 HTTP/1.1 Host: your-instance.example.ru Content-Type: application/json Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6 Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc Content-Length: 23 { "method": "DELETE" }
Success response
{ "status": "OK", "data": { "description": "Records successfully deleted." }
Error response
{ "status": "ERROR", "error_type": "SERVER", "errors": [ { "message": "You have no access to delete this records." } ] }
The REST API allows you to perform create, read, update, and delete (CRUD) operations on existing tables.
URL format:
Name | Value |
---|---|
Default URL | /rest/v1 |
CREATE operations
POST /rest/v1/table/{essence}
This method allows inserting one record in the defined table. It does not support multiple records insertion.
Parameters
Parameter | Value |
---|---|
column_name | column_value |
{ ... <column_name> => <column_value> ... }
READ operations
GET /rest/v1/table/{essence}This method returns multiple records for the essence table.
GET /rest/v1/table/{essence}/{sys_id}
This method retrieves one record from the essence table.
UPDATE operations
PUT /rest/v1/table/{essence}/{sys_id}
This method updates the specified record with the request body in the essence table.
PATCH /rest/v1/table/{essence}/{sys_id}
This method updates the specified record with the request body in the essence table.
Parameters
Parameter | Value |
---|---|
column_name | column_value |
{ ... <column_name> => <column_value> ... }
DELETE operations
DELETE /rest/v1/table/{essence}/{sys_id}
Deletes the specified record with the request body from the essence table.
Name | Description | Supported CRUD operations |
---|---|---|
sysparm_query | An encoded query string used to filter the results. | R |
sysparm_display_value | Data retrieval operation method. Also, may return both types of values.
Default: FALSE | CRU |
sysparm_exclude_reference_link | Flag that indicates whether to exclude Table API links for reference fields. Valid values:
Default: FALSE | CRU |
sysparm_fields | A comma-separated list of fields to return in the response. | CRU |
sysparm_view | Render the response according to the specified UI view (overridden by sysparm_fields). | CRU |
sysparm_limit | The maximum number of results returned per page. This parameter is equal to the self::CRUD_API_LIMIT_RECORDS. Default = 20 (for GET-queries). | R |
sysparm_page | Page number to offset records. Default = 1. |
Code Examples
{ "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" }, { "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": "155964310500000018", "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": "155964310500000026", "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": 1, "description": "", "subject": "" } ] }
{ "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" } ] }
{ "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" } ] }
{ "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" } ] }
{ "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": "" } ] }
{ "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
{ "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
{ "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" } ] }
{ "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, "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/rest/v1/table/user/155964310500000018" }, "closed_at": null, "display_name": "TSK002926 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/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": 155964310500000002, "state": 7, "description": null, "subject": "1" } ] }
DELETE operations
{ "status": "OK", "data": { "description": "Records successfully deleted." } }
{ "status": "ERROR", "error_type": "SERVER", "errors": [ { "message": "You have no access to delete this records." } ] }
Authorization
- No labels