The REST API allows you to perform the create, read, update, and delete (CRUD) operations on existing tables. Requests to perform the CRUD operations through the REST API are executed according to <![CDATA[ACL rules.

URL format:

NameValue
Default URL/rest/v1

Authorization


In Simple, three types of 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.

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.

Body parameter

ParameterValue
column_namecolumn_value


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


<![CDATA[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"
}


<![CDATA[{
  "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 operations



GET /rest/v1/table/{tableName}

This method returns multiple record query from the specified table.


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

This method retrieves one record from the specified table.

Parameters

NameDescription
sysparm_query

An encoded query string used to filter the results.

Value example: active=1.

sysparm_display_value

Data retrieval operation method. Also, may return both types of values.

  • true returns field display values.
  • false  returns database field values.

Default value: false.

sysparm_exclude_reference_linkFlag that indicates whether to exclude Table API links for reference fields.

Valid values:

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

Default value: false.

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 (overridden by sysparm_fields).

Value example: SP.

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.


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


<![CDATA[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


<![CDATA[{
    "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 /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.

Body parameter

ParameterValue
column_namecolumn_value


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


<![CDATA[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"
}


<![CDATA[{
    "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 metting",
        "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 metting",
        "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


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.

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

Success response

<![CDATA[{
    "status": "OK",
    "data": {
        "description": "Records successfully deleted."
}

Error response

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