Retrieving objects (POST)

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

Using the POST method, you can overcome the HTTP query length limitations. This request uses the same set of parameters and produces the identical results as GET method described in the section Retrieving objects (GET).

HTTP Method

POST

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.

POST parameters

Parameter	Description
`filters`	The filtering conditions. Each condition must contain a field name, value, and a filter operator: `name` – a field to filter the data records by. `value` – a value to use in the filtering operation. `operation` – a filter operator: equal (`=`), not equal (`<>`). For numeric and date values, filtering conditions also support using additional comparison operators, such as: `>`, `>=`, `<`, `<=`. INFO: For the correct spelling of Alloy Navigator field names, see How to refer to object fields when retrieving objects. This is an optional parameter.
`sort`	The collection of field and direction pairs for sorting: `property` – a field to sort by. `direction` – sorting order: ascending (asc), or descending (desc). This is an optional parameter.
`fields`	The fields to show in the result. This is an optional parameter. If missing, the API response includes all available fields.
`offset`	The number of records to skip. This is an optional parameter.
`limit`	The number of records to show in the result. This is an optional parameter.
`searchText`	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.

POST parameters should be specified in the request’s body, in JSON format.

POST body format:

{
	"filters":[
	{
		"name": "<filterName>",
		"value": "<filterValue>",
		"operation": "<filterOperation>"
		},
		...
	],
	"sort":[
	{
		"property":"<sortProperty>",
		"direction": "<sortDirection>"
		},
		...
	],

	"fields": ["<field1>", "<field2>",...],
		"offset": "<offset>",
		"limit": "<limit>"
}

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`	The list of retrieved data fields.	Array
`Name`	The field name.	String
`DataType`	The 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.

If the user is not authorized to access the object class, returned Data array will be empty. For details, see Retrieving objects (GET).

Example 1

Here is an example of how you can obtain a list of Consumables with set of fields: Invoice_Number, OID, Original_Cost; limited by two records, sorted in ascending order by the field OID, filtered by Original_Cost=114.95.

Request:

(POST) http://www.example.com/api/v2/Consumables

POST Body:

{
	"fields": [
		"OID",
		"Invoice_Number",
		"Original_Cost"
	],
	"sort":[
	{
		"property":"OID",
		"direction": "asc"
	}
	],
	"filters":[
	{
		"name": "Original Cost",
		"value": "114.95",
		"operation": "="
	}
	],
	"limit":2	
}

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Fields": [
		{
			"Name": "OID",
			"DataType": "string"
		},
		{
			"Name": "Invoice_Number",
			"DataType": "string"
		},
		{
			"Name": "IOriginal_Cost",
			"DataType": "money"
		}
		],
		"Data": [
			["CON000002","2014 - 0319","114.95"],
			["CON000003","2014 - 0319","114.95"]
		]
	}
}

Example 2

Here is an example of how you can obtain the information about one particular object of the Consumables class with OID=CON000002.