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:

NameValue
Default URL/rest/v1/table/

Authorization


In SimpeOne, 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 RemovedImage Added


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

.Parameters

Example:

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


Body parameter

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

ParameterValue
column_name column_value 


You can use the following parameters with this method:

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

  • true – returns field display values.
  • false – returns actual valuesfalseFlag that indicates true – exclude false – include falseusernameemailRender the response according to the specified UI view ()Value example SP
    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
    NameDescription
    sysparm_display_value
    • .

    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.

    Body parameter

    ParameterValuecolumn_namecolumn_value


    Notenote

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


    Example:

    Image Added

    Section


    Code Block
    languagejs
    themeEclipse
    titleCode SnippetHTTP
    linenumberstrue
    POST /rest/v1/table/dashboardtask HTTP/1.1
    Host: yoursandbox-instance01.dev.examplesimpleone.ru
    Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
    Content-Type: application/json
    Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6
    Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc
    Content-Length: 14143
    
     {  
        "subject": "Task created    by REST"
    }


    Code Block
    languagejs
    themeConfluence
    titleResponse
    linenumberstrue
    collapsetrue
    {
      "namestatus": "My DashboardOK",
                  
    "data": [
        {
          "sys_id": "166031411802010329",
          "descriptionstate":"Some description" "7",
          "priority": null,
                "refresh_timeurgency": null,
          "300impact": null,
     
     }
    Code Block
    languagejs
    themeConfluence
    titleResponse
    linenumberstrue
    collapsetrue
    {
        "statusassigned_user": "OK"null,
          "dataassignment_group": [null,
            {"wf_executing_activity": null,
          "closed_by": null,
          "sysfollowers_idlist": "165166624317136512"null,
          "parent_id": null,
          "applicationopened_idby": {null,
            "caller": {
            "value": "155931135900000002155931135900000001",
                    "link": "http://yoursandbox-instance01.dev.examplesimpleone.ru/rest/v1/table/sys_applicationuser/155931135900000002155931135900000001"
                },
          "contact": null,
          "descriptionservice": "Some description"null,
          "screenshot": null,
          "nameshort_description": "My Dashboard"null,
          "work_notes": null,
          "policyactive": "Open"true,
          "closed_at": null,
          "refreshsla_timedue": "300"null,
                "sys_createdupdated_at": "2022-0508-0412 1214:1021:4358",
                "sys_created_byat": { "2022-08-12 14:21:58",
          "description": null,
             "valuenumber": "155931135900000001TSK0000006",
          "subject": "Task created by REST",
          "linkadditional_comments": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001"null,
                },
       "comments": null,
             "sysopened_updated_at": "2022-0508-0412 1214:1021:4358",
          "due_date": null,
          "sysattention_updated_byrequired": {false,
              "company": null,
          "valueapproval_state": "155931135900000001not_requested",
          "sys_db_table_id": "155931135900000083",
          "display_name": "TSK0000006 Task created "link":by "http://your-instance.example.ru/rest/v1/table/user/155931135900000001"REST",
          "sys_updated_by": {
         }
       "value": "155931135900000001",
        }
        ]
    }

    READ operations

    GET /rest/v1/table/{tableName}

    This method returns multiple records for thespecified table.

    GET
    "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/
    {tableName}/{sys_id}

    This method retrieves one record from the specified table.

    user/155931135900000001"
          },
          "sys_created_by": {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
          }
        }
      ]
    }



    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:

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

    • 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.

    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
    languagejs
    themeEclipse
    titleHTTP
    linenumberstrue
    GET /rest/v1/table/task?sysparm_query=active=1&sysparm_fields=number,caller&sysparm_limit=1&sysparm_exclude_reference_link=1 HTTP/1.1
    Host: sandbox-01.dev.simpleone.ru
    Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu


    Code Block
    languagejs
    themeConfluence
    titleResponse
    linenumberstrue
    collapsetrue
    {
        "status": "OK",
        "data": [
            {
    

    Parameters

    NameDescriptionsysparm_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.

    • true returns field display values.
    • false  returns actual 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: 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.

    Note

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

    Section
    Code Block
    languagejs
    themeEclipse
    titleCode Snippet
    linenumberstrue
    GET /rest/v1/table/itsm_change_request HTTP/1.1
    Host: your-instance.example.ru
    Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6
    Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc
    Code Block
    languagejs
    themeConfluence
    titleResponse
    linenumberstrue
    collapsetrue
    {
        "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": {
                    "valuenumber": "155931135900000001TSK0000006",
                "caller": 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

    NameDescriptionsysparm_display_value

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

    • true – returns field display values.
    • false – returns actual 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: username,email.

    sysparm_view

    Render the response according to the specified UI view (overridden by sysparm_fields).

    Value example: SP.

      }
        ]
    }


    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 a specified record with the request body in the specified table. 

    Example:

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


    Example:

    Image Added

    Body parameter

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

    Section


    Code Block
    languagejs
    themeEclipse
    titleCode SnippetHTTP
    linenumberstrue
    PUT /rest/v1/table/usertask/164926188012940692166032552604350116 HTTP/1.1 
    Host: yoursandbox-instance01.dev.examplesimpleone.ru 
    Content-Type: application/json
    Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6
    Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|WqnmcBearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
    Content-Type: application/json
    Content-Length: 2620
    
    {
    	  "usernamestate": "john.doe3"
    }


    Code Block
    languagexmljs
    themeConfluence
    titlePUT Response
    linenumberstrue
    collapsetrue
    {
    {
        "status": "OK",
        "data": [
            {
                "sys_idstatus": "164926188012940692OK",
                "active"data": true,[
        {
            "authsys_keyid": null,
                "company166032552604350116": null,
                "date_format_id"state": {"3",
            "priority": null,
            "valueurgency": "159836398504170273"null,
            "impact": null,
            "linkassigned_user": "http://your-instance.example.ru/rest/v1/table/sys_date_format/159836398504170273"null,
            "assignment_group": null,
       },
         "wf_executing_activity": null,
            "departmentclosed_by": null,
                "displayfollowers_namelist": "John Doe"null,
                "emailparent_id": "johndoe@mail.com",
        null,
            "firstopened_nameby": "John"null,
            "caller":
        "language_id": {
        {
                "value": "156628684306200767155931135900000001",
                    "link": "http://yoursandbox-instance01.dev.examplesimpleone.ru/rest/v1/table/sys_languageuser/156628684306200767155931135900000001"
                },
                "last_namecontact": "Doe"null,
                "ldap_server_idservice": null,
                "locationscreenshot": null,
                "lockedshort_outdescription": falsenull,
                "log_out_on_all_deviceswork_notes": falsenull,
            "active": true,
            "photoclosed_idat": null,
                "primarysla_groupdue": null,
                "sourcesys_updated_at": "2022-08-13 13:46:11",
                "sys_created_at": "2022-0408-0612 1617:1832:0006",
            "description": null,
        "sys_created_by": {
        "number": "TSK0000014",
            "subject": "Kickoff meeting",
            "valueadditional_comments": "155931135900000001"null,
            "comments": null,
            "linkopened_at": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001"
    2022-08-12 17:32:06",
            "due_date": null,
         },
       "attention_required": false,
            "sys_db_table_idcompany": "155931135900000084",
            {
                "sys_updated_at": "2022-04-29 11:25:53value": "166032365806600708",
                "sys_updated_bylink": {"http://sandbox-01.dev.simpleone.ru/rest/v1/table/org_company/166032365806600708"
            },
            "valueapproval_state": "155931135900000001",
            not_requested",
            "linksys_db_table_id": "http://your-instance.example.ru/rest/v1/table/user/155931135900000001"155931135900000083",
            "display_name": "TSK0000014 Kickoff  }meeting",
                "timezonesys_updated_id": {
    by":
            {
                "value": "156076775207685877155931135900000001",
                    "link": "http://yoursandbox-instance01.dev.examplesimpleone.ru/rest/v1/table/user/155931135900000001"
            },
            "sys_timezone/156076775207685877"
    _created_by":
            {
                 }"value": "155931135900000001",
                "usernamelink": "john.doe"
    http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
            }
        }
        ]
    }

    DELETE operations

    DELETE
    ]
    }




    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.
    Note

    Example:

    Image Added

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

    Code Block
    languagejs
    themeEclipse
    titleCode SnippetHTTP
    linenumberstrue
    DELETE /rest/v1/table/dashboardsys_filter/165476748114102626166039918402151705 HTTP/1.1 
    Host: yoursandbox-instance01.dev.examplesimpleone.ru
    Content-Type: application/json
    Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6
    Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc
    Content-Length: 23
    
    {
    	"method": "DELETE"
    }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