Page History

The Table API allows you to perform the create, read, update, and delete (CRUD) operations on the existing tables.

The CRUD requests to the Table API are executed according to the ACL rules.

Table API URL format:

Name	Value
Default URL	/rest/v1/table/

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.

CREATE operation

Use the POST method to insert one record into the defined table. It does not support insertion of multiple records.

Example:

Code Block
POST /rest/v1/table/{tableName}

Body parameter

You can specify as many columns and their values as you need.

Parameter	Value
column_name	column_value

Use the following parameters with this method:

Parameter Description

sysparm_display_value

An operation method for data retrieval. It may return two types of values:

1 – returns field display values.
0 – returns database field values.

Default value: 0.

sysparm_exclude_reference_link

A flag indicating whether to exclude the Table API links (/rest/v1/table/) for reference fields.

Valid values:

1 – exclude Table API links for reference fields.
0 – include Table API links for reference fields.

Default value: 0.

sysparm_fields

A comma-separated list of fields to return to the response. The parameter supports the usage of dot-walking.

Note
Dot-walking does not work for the Schedule (sys_schedule) and Indication (sys_indication) tables as the system does not create records immediately after the method call.

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

From the set of columns of the view specified in sysparm_view, only those specified in sysparm_fields are returned. If the fields specified in sysparm_fields are not present in the selected view, the view will not be returned.

Info
If the parameter is not set, the response to the request returns the values of all columns of the table.

Note
You need to use raw JSON type of Body instead of form-data.

Example:

Section

Code Block

language	js
theme	Eclipse
title	HTTP
linenumbers	true

POST /rest/v1/table/task HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
Content-Type: application/json
Content-Length: 43

{
    "subject": "Task created by REST"
}

Code Block

language	js
theme	Confluence
title	Response
linenumbers	true
collapse	true

{
  "status": "OK",
  "data": [
    {
      "sys_id": "166031411802010329",
      "state": "7",
      "priority": null,
      "urgency": null,
      "impact": null,
      "assigned_user": null,
      "assignment_group": null,
      "wf_executing_activity": null,
      "closed_by": null,
      "followers_list": null,
      "parent_id": null,
      "opened_by": null,
      "caller": {
        "value": "155931135900000001",
        "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
      },
      "contact": null,
      "service": null,
      "screenshot": null,
      "short_description": null,
      "work_notes": null,
      "active": true,
      "closed_at": null,
      "sla_due": null,
      "sys_updated_at": "2022-08-12 14:21:58",
      "sys_created_at": "2022-08-12 14:21:58",
      "description": null,
      "number": "TSK0000006",
      "subject": "Task created by REST",
      "additional_comments": null,
      "comments": null,
      "opened_at": "2022-08-12 14:21:58",
      "due_date": null,
      "attention_required": false,
      "company": null,
      "approval_state": "not_requested",
      "sys_db_table_id": "155931135900000083",
      "display_name": "TSK0000006 Task created by REST",
      "sys_updated_by": {
        "value": "155931135900000001",
        "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
      },
      "sys_created_by": {
        "value": "155931135900000001",
        "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
      }
    }
  ]
}

READ operation

Read operations in SimpleOne are limited to the GET method.

To retrieve a single record from the specified table:

Code Block
GET /rest/v1/table/{tableName}/{sys_id}

To retrieve a multiple record query from the specified table:

Code Block
GET /rest/v1/table/{tableName}

Use the following parameters with this method.

Parameter

Description

sysparm_query

An encoded query string used to filter the results. The parameter supports the usage of dot-walking.

Value example: active=1.

To create a complex query, use the system name of the operators and the condition string.

sysparm_display_value

An operation method for data retrieval. It may return both types of values.

1 – returns field display values.
0 – returns database field 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:

1 – exclude Table API links for reference fields.
0 – include Table API links for reference fields.

Default value: 0.

sysparm_fields

A comma-separated list of fields to return to the response. The parameter supports the usage of dot-walking.

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.

From the set of columns of the view specified in sysparm_view, only those specified in sysparm_fields are returned. If the fields specified in sysparm_fields are not present in the selected view, the view will not be returned.

Info
If the parameter is not set
Info
If the parameter is not set, the response to the request returns the values of all columns of the table.

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 includes records from 21 to 60.

Default value: 1.

Note
Use raw JSON type of Body instead of form-data.

Section

Code Block

language	js
theme	Eclipse
title	HTTP
linenumbers	true

GET /rest/v1/table/task?sysparm_query=active=1&sysparm_fields=number,caller&sysparm_limit=1&sysparm_exclude_reference_link=true HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu

Code Block

language	js
theme	Confluence
title	Response
linenumbers	true
collapse	true

{
    "status": "OK",
    "data": [
        {
            "number": "TSK0000006",
            "caller": 155931135900000001
        }
    ]
}

UPDATE operation

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

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.

1 – returns field display values.
0 – returns database field 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:

1 – exclude Table API links for reference fields.
0 – include Table API links for reference fields.

Default value: 0.

sysparm_fields

A comma-separated list of fields to return to the response. The parameter supports the usage of dot-walking.

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

From the set of columns of the view specified in sysparm_view, only those specified in sysparm_fields are returned. If the fields specified in sysparm_fields are not present in the selected view, the view will not be returned.

Info
If the parameter is not set, the response to the request returns the values of all columns of the table.

Note
Use raw JSON type of Body instead of form-data.

PUT

Use it to update records in the specified table using the values defined in the request body.

Example:

Code Block

theme	Eclipse

PUT /rest/v1/table/{tableName}/{sys_id}

PATCH

Use it to partially update records. This method updates a specific record with the request body in the specified table.

Example:

Code Block
PATCH /rest/v1/table/{tableName}/{sys_id}

Section

Code Block

language	js
theme	Eclipse
title	HTTP
linenumbers	true

PUT /rest/v1/table/task/166032552604350116 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
Content-Type: application/json
Content-Length: 20

{
  "state": "3"
}

Code Block

language	js
theme	Confluence
title	Response
linenumbers	true
collapse	true

{
    "status": "OK",
    "data": [
    {
        "sys_id": "166032552604350116",
        "state": "3",
        "priority": null,
        "urgency": null,
        "impact": null,
        "assigned_user": null,
        "assignment_group": null,
        "wf_executing_activity": null,
        "closed_by": null,
        "followers_list": null,
        "parent_id": null,
        "opened_by": null,
        "caller":
        {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
        },
        "contact": null,
        "service": null,
        "screenshot": null,
        "short_description": null,
        "work_notes": null,
        "active": true,
        "closed_at": null,
        "sla_due": null,
        "sys_updated_at": "2022-08-13 13:46:11",
        "sys_created_at": "2022-08-12 17:32:06",
        "description": null,
        "number": "TSK0000014",
        "subject": "Kickoff meeting",
        "additional_comments": null,
        "comments": null,
        "opened_at": "2022-08-12 17:32:06",
        "due_date": null,
        "attention_required": false,
        "company":
        {
            "value": "166032365806600708",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/org_company/166032365806600708"
        },
        "approval_state": "not_requested",
        "sys_db_table_id": "155931135900000083",
        "display_name": "TSK0000014 Kickoff meeting",
        "sys_updated_by":
        {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
        },
        "sys_created_by":
        {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
        }
    }]
}

DELETE operation

Use this method to delete a specific 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:

Code Block

language	js
theme	Eclipse
title	HTTP
linenumbers	true

DELETE /rest/v1/table/sys_filter/166039918402151705 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu

Code Block

language	js
theme	Confluence
title	Success response
linenumbers	true

{
    "status": "OK",
    "data": {
        "description": "Records successfully deleted."
}

Code Block

language	js
theme	Confluence
title	Error response
linenumbers	true

{
    "status": "ERROR",
    "error_type": "SERVER",
    "errors": [
        {
            "message": "You have no access to delete this records."
        }
    ]
}

Table of Contents

absoluteUrl	true
class	fixedPosition

Page tree

Versions Compared

Old Version 11

New Version 12

Key

Authorization

CREATE operation

READ operation

UPDATE operation

PUT

PATCH

DELETE operation