Read Records of Specified Object
|
Method
|
GET
|
|
URL
|
/v2/<object_full_identifier>
|
|
Parameters
|
fields, incomingRelationships, filter, sort, limit, offset, exclude_total_count, data_format, suppress_ror
|
|
Response Content Type
|
application/json
|
Response Example
The response is a JSON representation of a list of all retrieved records. Following is an example Status Code 200 response for the Showcase object.
[
{
"__object_identifier": "io_showcase",
"io_showcase_phone_number": "+1 (650) 123456",
"io_search_filter_file_object": null,
"io_owner": "bbbf0872-b9dc-11e0-adfd-00ff8314382b",
"io_showcase_document": null,
"io_private": false,
"io_platform_changes_permitted": null,
.
.
},
{...}, {...}, ..., {...}
]
{
"__object_identifier": "io_showcase",
"io_showcase_phone_number": "+1 (650) 123456",
"io_search_filter_file_object": null,
"io_owner": "bbbf0872-b9dc-11e0-adfd-00ff8314382b",
"io_showcase_document": null,
"io_private": false,
"io_platform_changes_permitted": null,
.
.
},
{...}, {...}, ..., {...}
]
 |
Each returned record includes the __object_identifier pseudo-field, which contains the full identifier of the object to which the record belongs.
|
|
Parameter
|
Description
|
Data Type
|
Example
|
|---|---|---|---|
|
fields
|
Object fields to be retrieved. Eager loading is supported in depth, and related record fields can be eager-loaded if relationships between records exist.
If not specified, all object fields are retrieved by default.
|
String
|
Retrieve only the uuid, owner, private, active, and deleted fields for each record:
/v2/<object_full_identifier>?fields=io_uuid,io_owner,io_private,io_active,io_deleted
|
|
incomingRelationships
|
Incoming relationships of the object to use to retrieve related records.
|
String
|
Retrieve the related records for the application_log_related_to incoming relationship for each record:
/v2/<object_full_identifier>?incomingRelationships=application_log_related_to
|
|
filter
|
Filtering condition on records to retrieve. The SMQL WHERE clause is supported for filtering eager-loaded fields.
If not specified, all undeleted records are retrieved by default.
|
String
|
Retrieve only the records updated by the system user:
/v2/<object_full_identifier>?filter=io_updated_by.io_username='system'
|
|
sort
|
Sorting criteria for retrieved records. The SMQL ORDER BY clause is supported for sorting eager-loaded fields. Ascending (ASC) and descending (DESC) criteria are supported. ASC is the default.
If not specified, records are retrieved in no specific order.
|
String
|
Retrieve all records sorted by creation date in descending order:
/v2/<object_full_identifier>?sort=io_created_on+DESC
Retrieve all records sorted by the full name of the user who created the record (default ascending) and by the creation date in descending order:
/v2/<object_full_identifier>?sort=io_created_by.io_full_name,io_created_on+DESC
|
|
limit
|
The number of records to retrieve. SMQL LIMIT clause syntax is supported. If specified, the response includes the X-Total-Count header with the total count of records that can be be retrieved without the limit. Consider using exclude_total_count if calculation of this value is not performant.
If not specified, and no filtering specified, all undeleted records are retrieved.
|
Integer
|
Retrieve 100 records for an object:
/v2/<object_full_identifier>?limit=100
|
|
offset
|
Offset to use to retrieve records. ServiceMax recommends combining this parameter with the sort parameter. SQML OFFSET clause syntax is supported
If not specified, records are retrieved with no offset.
|
Integer
|
Retrieve the next 100 records after the first 500, ordered by Name:
/v2/<object_full_identifier>?sort=io_name&limit=100&offset=500
|
|
exclude_total_count
|
Set this flag to exclude the X-Total-Count header, which is provided by default when you use limit to specify the number of records returned.
If limit is not set and the total number of selected records is large, performance may be impacted depending on permissions configuration. In these cases, use this parameter to reduce the number of calculation iterations of the total count.
|
Boolean
|
Retrieve the next 100 records after the first 500 sorted by Name without calculating the total count:
/v2/<object_full_identifier>?sort=io_name&limit=100&offset=500&exclude_total_count=true
|
|
data_format
|
The output data format. Supported values are basic (default) and extended.
The basic format corresponds to the example response shown above. The extended format includes additional information for specific data types. For more information, see Extended Output Data Format.
|
String
|
Retrieve a list of records with extended output data:
/v2/<object_full_identifier>?data_format=extended
|
|
suppress_ror
|
Whether to bypass recalculation for recalculate-on-read fields.When specified, RoR fields are read instead of recalculated, and their values are returned from the database.
|
Boolean
|
Retrieve a list of records with recalculate-on-read suppressed:
/v2/<object_full_identifier>?suppress_ror=true
|
Error Response Messages
|
HTTP Status Code
|
Error Type
|
Error Message
|
|---|---|---|
|
400
|
missing_parameter_error
|
Missing or invalid required parameter
|
|
400
|
smql_query_error
|
SMQL query error
|
|
400
|
serialization_error
|
Serialization error
|
|
500
|
server_error
|
Server error
|
Access Control
This REST API endpoint respects access control and permissions for each record. Data that users lack permissions to read is not returned. All authenticated users (for example, with the Standard User role) can execute this REST endpoint.
Examples
• Retrieve all undeleted objects:
GET https://<server>/v2/io_object
• Retrieve all undeleted objects ordered by identifier:
GET https:// <server >/v2/io_object?sort=io_identifier
• Retrieve the first 100 undeleted objects, sorted by name:
GET https:// <server>/v2/io_object?sort=io_name&limit=100
• Retrieve the first 100 undeleted objects, sorted by name (descending), and only a subset of the associated fields:
GET https://<server>/v2/io_object?fields=io_name,io_uuid&sort=io_name+desc&limit=100
• Retrieve all undeleted objects created after 01/01/2015, sorted by identifier, and only a subset of the associated fields:
GET https:// <server>/v2/io_object?fields=io_uuid,io_owner,io_identifier,io_created_on,io_created_by,io_active,io_private&filter=io_created_on>'2015-01-01'&sort=io_identifier
• Retrieve all undeleted objects updated by the system user:
GET https:// <server>/v2/io_object?fields=io_name,io_uuid,io_created_by.io_username,io_updated_by.io_username&filter=io_updated_by.io_username='system'
• Retrieve all undeleted Showcase records, including all fields of the object and of the related owner:
GET https://<server>/v2/io_showcase?fields=*,io_owner.*
• Retrieve all related Showcase Details of Showcase records:
GET https://<server>/v2/io_showcase?incomingRelationships=io_showcase_detail_showcase
GET https://<server>/v2/io_user?incomingRelationships=io_role_io_users,io_group_io_users ((<source_object_full_identifier>)_(<relationship_full_identifier>))
For more information: