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.

Requests

CRUD requests to

perform

the

CRUD operations through the REST

Table API are executed according to the ACL rules.


Table API URL format:

NameValue
Default URL/rest/v1/table/

Authorization


In Simple, three Two types of Table API request authorization are supported:

No Authrequest does not require authorization.

  • Basic Auth authentication involves sending a verified username and password with the request.
  • Bearer Tokenauthentication with an access key. The token is a text string, included in the request header.

Image Modified


CREATE operations

POST /rest/v1/table/{tableName}


This method allows for inserting one record in

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

insertion.

.

Example:

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


Body parameter

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

ParameterValue
column_namename column_valuevalue 
Note


You

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

can use the following parameters with this method:

Image Removed

Section Code Block
languagejs
themeEclipse
titleHTTP
linenumberstrue
POST
ParameterDescription
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_linkA 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.

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


Code Block
languagejs
themeEclipse
titleHTTP
linenumberstrue
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"
}


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
languagejs
themeConfluence
titleResponse
linenumberstrue
collapsetrue
{
  "status": "OK",
  "data": [
    {
Code Block
languagejs
themeConfluence
titleResponse
linenumberstrue
collapsetrue
{
  "status": "OK",
  "data": [
    {
      "sys_id": "166031411802010329",
      "state": "7",
      "priority": null,
      "urgencysys_id": null"166031411802010329",
      "impactstate": null"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 operations

GET /rest/v1/table/{tableName}This method returns multiple record query

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}
This method retrieves one record

To retrieve multiple record query from the specified table

.

:

Parameters

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


You can use the following parameters with this method:

ParameterNameDescription
sysparm_query

An encoded query string used to filter the results.

Value example: active=1.

sysparm_display_value

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

  • true returns 1 – returns field display values.
  • false  0 – returns database field values.

Default value: false0.

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

Valid values:

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

Default value: false 0.

sysparm_fields

A comma-separated list of fields to return to the response.

Value example: number,caller.

sysparm_view

Render the response according to the specified UI view (The response contains the fields of the form view defined by this parameter. Note that it can be overridden by sysparm_fields).

Value exampleDefault value: SP Default.

sysparm_limit

The maximum number of results returned by query.

Default value: 20 (for GET-queries).

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

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


Image RemovedImage Added

Section


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


Code Block
languagejs
themeConfluence
titleResponse
linenumberstrue
collapsetrue
{
    "status": "OK",
    "data": [
        {
            "number": "TSK0000006",
            "caller": 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 
    ]
}


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.

ParameterValue
column_namecolumn_value


Note

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

You can use the following parameters for the PUT and PATCH methods:

ParameterDescription
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_linkA 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.

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
themeEclipse
PUT /rest/v1/table/{tableName}/{sys_id}


PATCH

Use it to partially update records. This method updates

the specified record with

a specified record with the request body in the specified table. 

Example:

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

This method updates the specified record with the request body in the specified table.


Example:

Body parameter

ParameterValuecolumn_namecolumn_value NoteYou need to use raw JSON type of Body instead of form-data.

Image Modified

Section


Code Block
languagejs
themeEclipse
titleHTTP
linenumberstrue
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
languagejs
themeConfluence
titleResponse
linenumberstrue
collapsetrue
{
    "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 mettingmeeting",
        "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 mettingmeeting",
        "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 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}

Deletes the specified record with the request body from the specified table.


You can receive one of There are two possible responses:

  • When the a record was successfully deleted.
  • When an error occurred.

Example:

Image Modified

Code Block
languagejs
themeEclipse
titleHTTP
linenumberstrue
DELETE /rest/v1/table/sys_filter/166039918402151705 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu

Success response

Code Block
languagejs
themeConfluence
linenumberstrue
{
    "status": "OK",
    "data": {
        "description": "Records successfully deleted."
}

Error response

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


Table of Contents
absoluteUrltrue
classfixedPosition