You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 43 Next »

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

URL format:

NameValue
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

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

Body parameter

ParameterValue
column_namecolumn_value

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

Code Snippet
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"  
 }
Response 
{
    "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

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

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

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

Code Snippet
GET /rest/v1/table/itsm_change_request HTTP/1.1
Host: your-instance.example.ru
Authorization: Basic am91bi5kb4U6MTIzNDU2Nzg6
Cookie: SERVERID=srv-ocXctExSS6esqqmrg3ZkKA|Wqnmc
Response 
{
    "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

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

Body parameter

ParameterValue
column_namecolumn_value

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

Code Snippet
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"
}
PUT Response 
{
    "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.

Code Snippet
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."
        }
    ]
}

  • No labels

© 2019-2023, SimpleOne

https://simpleone.ru