API User's Guide

Retrieving objects (GET)

Description

The API provides the ability to retrieve information about Alloy Navigator objects of the specified object class. You can specify filtering and sorting criteria for returned objects and search objects using partial text fragments or keywords.

TIP: To retrieve the values of the primary key from the database specify the ID field in the request parameter. For details, see Example 3.

TIP: In order to retrieve a single object specify the object’s OID or ID value as a filter. For details, see Example 4.

HTTP method

GET

API URL
http://www.example.com/api/v2/<objectClass>
URL parameters
Parameter Description

objectClass

The object class name.

Examples: Incidents, Computers.

INFO: For the correct spelling of Alloy Navigator object class names, see Supported Alloy Navigator object classes.
GET parameters (query string)

Additional parameters should be specified in the URL query string.

Parameter Description

par_sort_desc

The fields by which to sort the result in descending order. The field names must be separated by a comma.

This is an optional parameter. Only one sorting direction can be specified, either par_sort_desc or par_sort_asc.

INFO: For the correct spelling of Alloy Navigator field names, see How to refer to object fields when retrieving objects.

par_sort_asc

The fields by which to sort the result in ascending order. Field names must be separated by a comma.

This is an optional parameter. Only one sorting direction can be specified, either par_sort_desc or par_sort_asc.

par_fields

The comma-separated list of field names to include in the result.

This is an optional parameter. If missing, the API response includes all available fields.

par_offset

The number of records to skip. Should be used in conjunction with par_limit to paginate results.

This is an optional parameter.

par_limit

The number of records to return. Can be used in conjunction with par_offset to paginate results.

This is an optional parameter.

<fieldName1>

<fieldName2>

...

The filtering criteria.

Example: Priority=High

This is an optional parameter.

<par_search_text>

The search string by which to search the retrieved objects. Can use partial text fragments or keywords.

Example: par_search_text=Outlook

This is an optional parameter.

NOTE: The search is performed in frequently-used text fields, i.e. in the text fields where objects store all important information. Every object class has a different set of such fields. For details, see Help: Frequently-used text fields.

TIP: When using impersonation, you can perform the search operation only for those object classes that are available through the Self Service Portal. For details, see Performing operations on behalf of other users.

NOTE: Note that the URL length is limited by the web server settings. If your parameters push the total size of the URL over limit you should use the POST request. For details, see Retrieving objects (POST).

Response Format

Object data is returned as two arrays:

  • Fields: The name and data type of the fields specified in the request
  • Data: Field values for each object record
{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Fields": [
		{
			"Name": "Field_1",
			"DataType": "string/int/guid/..."
		},
		{
			"Name": "Field_2",
			"DataType": "string/int/guid/..."
		},
		//...
		],
		"Data": [
			["Field_1 data","Field_2 data",...],
			//...
		]
	}
}
Property Description Format
Fields

List of retrieved data fields

Array
Name

Field name.

String
DataType

Field data type.

String
Data

The Data array. Object records are returned as nested arrays. Field values are listed in the same order as field definitions in the Fields array.

Array

In case of an invalid request the server returns an error message. The following errors may appear:

Error message Description
Authorization has been denied for this request.

The Authorization header is missing, or the token has expired.
Requested object is of unknown class.

The Object Class with the specified name was not found.
Field <name> is unknown.

The field with the specified name was not found.

NOTE: If the user is not authorized to access the Object Class, the returned Data array will be empty. For details, see Example 2.

Example 1

This is an example of how you can specify fields that you want to be retrieved. Below is a request for a list of Consumables objects limited to two records and sorted by Original Cost in ascending order. Only Invoice_Number, OID and Original_Cost are requested.

Request:

(GET) http://www.example.com/api/v2/Consumables?par_fields=Invoice_Number,OID,Original_Cost&par_limit=2&par_sort_asc=Original_Cost

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		Fields": [
		{
			"Name": "Invoice_Number",
			"DataType": "string"
		},
		{
			"Name": "OID",
			"DataType": "string"
		},
		{
			"Name": "Original_Cost",
			"DataType": "money"
		}
		],
		"Data": [
			["19289819818","CON000001","139.98"],
			["2014 - 0319","CON000002","114.95"]
		]
	}
}
Example 2

When the request from example 1 is sent by the user who is not authorized to access the Consumables object class, no data is returned.

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Fields": [
		{
			"Name": "Invoice_Number",
			"DataType": "string"
		},
		{
			"Name": "OID",
			"DataType": "string"
		},
			
		{
			"Name": "Original_Cost",
			"DataType": "money"
		}
		],
		"Data": []
	}
}
Example 3

This is an example of how you can obtain the database record ID. For more information, see Object identification in Alloy Navigator.

The request calls for a list of Purchase Order Items objects. Only the data contained in fields PO_Number, Line and ID is returned.

HTTP(GET) http://www.example.com/api/v2/Purchase Order Items?par_fields=PO_Number%2CLine%2CID

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Fields": [
		{
			"Name": "PO_Number",
			"DataType": "string"
		},
		{
			"Name": "Line",
			"DataType": "int"
		},
			
		{
			"Name": "ID",
			"DataType": "guid"
		}
		],
		"Data": [
			["PO0001","1","{EB6D7E24-59CA-4532-B365-451724A7B880}"],
			["PO0002","1","{A1C93151-8F65-4E15-BE22-868C21C64E12}"],
			//...
		]
	}
}
Example 4

Here is an example of how you can get the information about one object in the Software Catalog class. You set ID={3A9F4B6A-BEF7-4932-A5EF-003AF7ADE35C} as a filter and retrieve the following fields: ID, Product_Name, Manufacturer, Platform, and Version.

Request:

(GET) http://www.example.com/api/v2/SoftwareCatalog?par_fields=ID,Product_Name,Manufacturer,Platform,Version&ID={3A9F4B6A-BEF7-4932-A5EF-003AF7ADE35C

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Fields": [
		{
			"Name": "ID",
			"DataType": "guid"
		},
		{
			"Name": "Product_Name",
			"DataType": "string"
		},
		{
			"Name": "Platform",
			"DataType": "string"
		},
		{
			"Name": "Manufacturer",
			"DataType": "string"
		},
		{
			"Name": "Version",
			"DataType": "string"
		}
		],
		"Data": [
			[
			"{3A9F4B6A-BEF7-4932-A5EF-003AF7ADE35C}","Dell Touchpad",
			"ALPS ELECTRIC CO., LTD.","Windows","7.1107.101.210"
			]
		]
	}
}