Response Fields

The following table shows the fields that are returned in the response.

Field

Description

Example

totalResults

Total number of elements in the database.

<totalResults></totalResults>

resultsPerPage

Number of items requested per page.

<resultsPerPage></resultsPerPage>

startIndex

The index of the first element returned.

<startIndex></startIndex>

nextPage

refURL to next page.

<nextPage></nextPage>

prevPage

refURL to previous page.

<prevPage></prevPage>

firstPage

refURL to first page.

<firstPage></firstPage>

lastPage

refURL to last page.

<lastPage></lastPage>

searchTerm

String value.

<searchTerm></searchTerm>

sortTerm

String value.

<sortTerm></sortTerm>

Important Notes

The following is a list of caveats and important notes about Pagination.

If you request a startIndex that is greater than total items, a full last page is returned.

The lastPage should always return a full last page.

The firstPage should always return a full first page (starting at 0).

The nextPage is null if there is no nextPage (on last page).

The prevPage is null if there is no prevPage (on first page).

Search API

This section provides an overview of Search API, defines the search parameter, shows a search example, and outlines the default search values for existing configuration objects.

Overview

The various list API commands take an optional search parameter, which limits returned results to the configuration objects that match the search string.

The parameter is: q=<search_string>

You can perform a search on a predefined set of default fields for each configuration object. Typically, this is the name and description field, or the object's equivalent.

Search is subject to the following restrictions:

Case-insensitive. The search is case insensitive. Searching for https://<server>/unifiedconfig/config/attribute?q= att.0001 or https://<server>/unifiedconfig/config/attribute?q= ATT.0001 will yield the same results

String-only searches.

Sql wildcards are not supported.
"?", "*" and other wildcards are not supported.

The <search_string> will match any part of the default fields.
The lookup looks for the <search_string> as part of the searchable items. i.e. if you have attributes named as LocationBoston, LocationBoulder, LocationLondon; the search query https://<server>/unifiedconfig/config/attribute?q=location will return all 3 attributes in the result.
The search query https://<server>/unifiedconfig/config/attribute?q=LocationB will return attributes with names LocationBoston and LocationBoulder in results.

The <search_string> is treated as a single string.

The <search_string> will match on any of the default fields returning that record.
Consider a scenario where you have an attribute named "LocationMktBoston" with the description being "This tells if the marketing agent is located in Boston". A search query such as https://<server>/unifiedconfig/config/attribute?q=marketing will return this attribute.

The search criteria are applied before the pagination parameters, so that pagination's totalResults value lists the total number of elements in the database that meet the search criteria.

Example

For example, a search for all the Attributes whose name or description contains "supervisor" would be as follows:

Asynchronous API

This section explains how to make an asynchronous (async) call and outlines the expected responses. It describes the three supported operations for this API: create, update, and delete. The section also provides four use cases, and explains the
exceptions returned and the conditions under which they are returned.

The examples shown describe how to use the async feature to create an Attribute.

Create

Syntax

URL: https://<server>/unifiedconfig/config/attribute?async=true

HTTP Method: POST

Response

If a request is successfully put on the queue for processing—that is, if it has passed the validation check before getting on queue—the result is the HTTP Response 202 Accepted with the following Location URL in the header, for polling the status of the request:

Exceptions

Update

Syntax

URL: https://<server>/unifiedconfig/config/attribute/<ID>?async=true

HTTP Method: PUT

Response

If a request is successfully put on the queue for processing—that is, if it has passed the validation check before getting on queue—the result is the HTTP Response 202 Accepted with the following Location URL in the header, for polling the status of the request:

URL: https://<server>/unifiedconfig/config/asyncrequeststatus/<id>

And, the following XML content is returned:

<asyncResult>
<progress>IN_QUEUE</progress>
</asyncResult>

Exceptions

Delete

Syntax

URL: https://<server>/unifiedconfig/config/attribute/<ID>?async=true

HTTP Method: DELETE

Response

If a request is successfully put on the queue for processing—that is, if it has passed the validation check before getting on queue—the result is the HTTP Response 202 Accepted with the following Location URL in the header, for polling the status of the request:

4) Depending on timing, as this is a very short state, the system may return the following status to indicate that the request has been taken out of queue and is being processed:

202 Accepted status with progress of IN_PROGRESS.

5) User polls the status again using the previously provided URL:

https://<server>/unifiedconfig/config/asyncrequeststatus/<id>

6) System returns the following status to indicate that the system capacity has been exceeded for Attribute:

400 Bad Request, with error text.

Exceptions

This section explains the exceptions returned and the conditions under which they are returned:

Exceptions:

Tasks that cannot be put on the queue due to max capacity return an HTTP status code of 503, with an API error indicating the queue is full.

If a task reaches its max time in queue of 30 seconds, it is removed from the queue. On the next poll for the status of this task, an HTTP status code of 503 is returned, with an API error indicating timed out.