Contents

• API conventions
• General Usage
• Pagination
• Search API
• Sort API
• Asynchronous API
• Create
• Update
• Delete
• Values
• Use Case
• Exceptions

API conventions

---

• General Usage
• Pagination
• Search API
• Sort API
• Asynchronous API

General Usage

Object ID <id>

Object ID <id>: Using http POST to create all objects generates an id for the object.

The DELETE, GET, and PUT operations for these objects are performed using the object ID in the REST URL. For example:

• Use this URL to view results for a specific bucket interval: https://<ServerIP>/unifiedconfig/config/bucketinterval/<id>/results
• Use this URL to delete a bucket interval: https://<ServerIP>/unifiedconfig/config/bucketinterval/<id>

Use the List(GET) function to identify the object IDs.

<results>
<pageInfo>
....
</pageInfo>
<bucketIntervals>
<bucketInterval>...</bucketInterval>
<bucketInterval>...</bucketInterval>
</bucketIntervals>
</results>

changeStamp

A changeStamp is a required parameter for the body of a PUT (update) operation for objects.

If you do not provide a changeStamp, the update fails. This mechanism is in place so that two clients cannot edit the record at the same time.

If the update is successful, the database increments the changeStamp by 1.

Passwords

For security, the APIs do not return passwords in cleartext. Password elements are masked (******).

HTTP responses

All errors are returned as HTTP 1.1 Status Codes. The common codes used by the Unified CCE Developers Guide APIs are:

• 200 OK: Success.
• 201 Created: The requested item was created.
• 202 Accepted: The request was accepted. Generally, a URL is provided to obtain additional details, for example, for polling the OAuth status.
• 400 Bad Request: The request is invalid. Information returned in the ApiErrors message—example below—shows more details.
• 401 Unauthorized: The authentication credentials were not supplied or were incorrect.
• 404 Not Found: The URI requested does not exist on the server.
• 405 Method Not Allowed: The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
• 500 Internal Server Error: There is a problem on the server. Submit a post to the Unified CCE Developers Guide Forum explaining what you did and the response sent from the server.

Field specific and database errors are provided in an XML error message with the format:

<apiErrors>
    <apiError>
        <errorType>Type of Error</errorType>
        <errorData>Field Error Occurred</errorData>
        <errorMessage>A Description of the Error</errorMessage>
        <errorDetail>Extra information about the Error</errorDetail>
    </apiError>
<apiErrors>

ErrorDetail examples

An example of an errorDetail field for an error type such as invalidInput.outOfRange is as follows:

<errorDetail>
    <min>0</min>
    <max>5</max>
</errorDetail>

An example of an errorDetail field for error types such as invalidInput.fieldLengthExceeded, limitExceeded.expandedCallVariableSize, and limitExceeded.totalExpandedCallVariableSize is:

<errorDetail>
    <max>5</max>
</errorDetail>

Note	The above list of error types is not a comprehensive list and is given only as an example.

ErrorDetail references

Errors of type referenceViolation include the following kinds of error detail fields, for example: totalCount, totalShown, referenceType, name, refURL, id, and deleted.

For example, if you try to delete a bucket interval that is referenced by a call type, the error details look like this:

<errorDetail>
    <totalCount>1000</totalCount>
    <totalShown>5</totalShown>
    <referenceType>Attribute</referenceType>
    <references>
        <reference>
            <name>attribute1</name>
            <refURL>/unifiedconfig/config/attribute/5000</refURL>
        </reference>
       <reference>
            <name>attribute2</name>
            <refURL>/unifiedconfig/config/attribute/5001</refURL>
        </reference>
       <reference>
            <name>attribute3</name>
            <refURL>/unifiedconfig/config/attribute/5002</refURL>
        </reference>
       <reference>
            <name>attribute4</name>
            <refURL>/unifiedconfig/config/attribute/5003</refURL>
        </reference>
       <reference>
            <name>attribute5</name>
            <refURL>/unifiedconfig/config/attribute/5004</refURL>
        </reference>
    </references>
</errorDetail>

ErrorDetail script references

For items that are referenced by the script editor, the following detail fields are included for each Master_Script entry: name, ID, and versions.

API behavior

For any field except list elements, you can specify the same attribute more than once. However, the API takes the last attribute that you specify for that field.

For example, if you create an Agent using the following XML:

<agent>
<agentId>00370</agentId>
<description>bling</description>
<person>
   <firstName>fred</firstName>
   <firstName>bill</firstName>
   <lastName>smithx</lastName>
   <loginName>fsmithax</loginName>
   <password>freddieboy</password>
   <loginEnabled>true</loginEnabled>
   <changeStamp>0</changeStamp>
</person>
</agent>

Notice that <firstName> is specified twice:

 
<firstName>fred</firstName>
<firstName>bill</firstName>

The API takes the second <firstName> attribute and sets the Agent's first name to:

bill

Be aware that this type of behavior is common to all the APIs.

Pagination

The Pagination of the API provides information about how many objects are in the database, as well as pointers to the first, last, previous, and next page of items, if available.

This section outlines the Pagination parameters, shows a sample response, and describes the fields that are returned in the response. It also provides important notes about Pagination.

The following table shows the Pagination parameters that you can set.

Table 1 

Parameter name	Explanation	Notes
startIndex	Specifies the index of the element, at which to start.	Zero-based: 0 is the first element. DEFAULT = 0.
resultsPerPage	Specifies the number of elements to retrieve.	MIN=1. DEFAULT=25 MAX=100.

Note	The following is an example of how to use the Pagination parameters when listing a specific element type: https://<server>/unifiedconfig/config/bucketinterval?startIndex=0&resultsPerPage=5

Response

The following shows an example XML response:

<pageInfo>
						<resultsPerPage>5</resultsPerPage>
						<startindex>0</startIndex>
						<totalResults>10</totalResults>													
						<firstPage> http://<server>/bucketInterval? sort=name%20asc&resultsPerPage=5</firstPage>																					
						<lastPage> http://<server>/bucketInterval? sort=name%20asc&startIndex=8&resultsPerPage=5</lastPage>
						<prevPage/>
						<nextPage> http://<server>/bucketInterval?sort=name%20asc&startIndex=2&resultsPerPage=5</nextPage>
						<sortTerm>name asc</sortTerm>
</pageInfo>

<bucketIntervals>
   <bucketInterval/>
   <bucketInterval/>
</bucketIntervals>

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:

https://<server>/unifiedconfig/config/attribute?q=supervisor

XML returned

The following XML content is returned when the Search API is called:

<results>
		<pageInfo>
				<firstPage>
https://<server>/unifiedconfig/config/attribute?q=att.00001&sort=name%20asc&resultsPerPage=25
				</firstPage>
				<lastPage>
https://<server>/unifiedconfig/config/attribute?q=att.00001&sort=name%20asc&startIndex=0&resultsPerPage=25
				</lastPage>
				<resultsPerPage>25</resultsPerPage>
				<searchTerm>att.00001</searchTerm>
				<sortTerm>name asc</sortTerm>
				<startIndex>0</startIndex>
				<totalResults>1</totalResults>
		</pageInfo>
		<attributes>
					<attribute>
							<changeStamp>1</changeStamp>
							<refURL>/unifiedconfig/config/attribute/5000</refURL>
							<dataType>4</dataType>
							<defaultValue>1</defaultValue>
							<description>XXXXY</description>
							<name>Att.00001</name>
					</attribute>
			</attributes>
</results>

Note	If you include Sort, a <sortTerm> tagged value is returned.

Default search values

The table below shows the default search values for existing configuration objects.

Configuration object	Default search value
bucketIntervals	name
agent	name description
attribute	name description
precisionqueue	name description

Sort API

This section provides an overview of Sort API, defines the sort parameter, shows a sort example and the allowable sort attributes, and discusses error results.

Overview

You can sort list API results for each configuration object, in either an ascending or descending manner.

The parameter is: sort=<attributeName> [asc|desc], where:

• attributeName is the name of the field as returned in the XML and is case-sensitive.
• asc|desc are optional and case-insensitive.
• asc stands for ascending sort, which is the default.
• desc stands for descending sort.

Note	Only the first sort argument on a GET query string is used to perform the sort operation. The others are ignored.

The sort option is applied after the search parameter and before the pagination parameters. The sort option can be specified by itself. The default sort field is the name field or equivalent.

Strings are returned in linguistic sort order. For example, Alpha, abel, Beta, bagel is sorted as:

• abel
• Alpha
• bagel
• Beta

Integer fields are sorted in integer order, not linguistic order. For example: 6, 12, 100 is sorted as 6, 12, 100.

Example

For example, to find all the Attributes whose name or description contains supervisor, and to sort ascending by name:

https://<server>/unifiedconfig/config/attribute?q=supervisor&sort=name

And, to find all the DialedNumbers and sort descending by description:

https://<server>/unifiedconfig/config/dialednumber?sort=description desc

XML returned

The following XML content is returned when the Search API is called:

<results>
 <pageInfo>
  	<firstPage>
https://<server>/unifiedconfig/config/attribute?q=att.0000&sort=name%20asc&resultsPerPage=25
			</firstPage> 
  	<lastPage>
https://<server>/unifiedconfig/config/attribute?q=att.0000&sort=name%20asc&startIndex=0&resultsPerPage=25
			</lastPage> 
 	 <resultsPerPage>25</resultsPerPage> 
 	 <searchTerm>att.0000</searchTerm> 
  	<sortTerm>name asc</sortTerm> 
  	<startIndex>0</startIndex> 
 	 <totalResults>9</totalResults> 
  </pageInfo>
 	<attributes>
					<attribute>
  			<changeStamp>1</changeStamp> 
  			<refURL>/unifiedconfig/config/attribute/5000</refURL> 
  			<dataType>4</dataType> 
  			<defaultValue>1</defaultValue> 
  			<description>XXXXY</description> 
  			<name>Att.00001</name> 
  </attribute>
 	<attribute>
  			<changeStamp>0</changeStamp> 
  			<refURL>/unifiedconfig/config/attribute/5001</refURL> 
  			<dataType>4</dataType> 
  			<defaultValue>1</defaultValue> 
  			<description>XXXXX</description> 
  			<name>Att.00002</name> 
  </attribute>
 	<attribute>
 			 <changeStamp>0</changeStamp> 
  			<refURL>/unifiedconfig/config/attribute/5002</refURL> 
  			<dataType>4</dataType> 
  			<defaultValue>1</defaultValue> 
  			<description>XXXXX</description> 
  			<name>Att.00003</name> 
  </attribute>
	 <attribute>
  			<changeStamp>0</changeStamp> 
  			<refURL>/unifiedconfig/config/attribute/5003</refURL> 
  			<dataType>4</dataType> 
  			<defaultValue>1</defaultValue> 
  			<description>XXXXX</description> 
  			<name>Att.00004</name> 
  </attribute>
 </attributes>
</results>

Note	For sort only commands, the <searchTerm> is not returned.

Allowable sort attributes

The table below shows the allowable sort attributes for existing configuration objects.

Configuration object	Allowable sort attributes
bucketIntervals	name (default) upperBound1-9
agent	description supervisor agentID agentStateTrace person.userName person.firstName person.lastName person.loginEnabled
attribute	name (default) description dataType defaultValue
precisionqueue	name (default) description

Error results

Specifying an invalid sort field or sort option (asc|desc) or too many parameters in the sort request results in an apiError being returned with ErrorType set to invalidInput.badSortField.

For example, the sort parameter: sort=name asc extra results in the following apiError:

<apiErrors>
   <apiError>
     <errorType>invalidInput.badSortField</errorType>
     <errorData>name asc extra</errorData>
     <errorMessage> .... </errorMessage>
  </apiError>
</apiErrors>

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
• Update
• Delete
• Values
• Use Case
• Exceptions

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:

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

And, the following XML content is returned:

<results>
		<pageInfo>
				<firstPage>
https://<server>/unifiedconfig/config/attribute?sort=name%20asc&resultsPerPage=25
				</firstPage>
				<lastPage>https://<server>/unifiedconfig/config/attribute?sort=name%20asc&startIndex=9975&resultsPerPage=25
				</lastPage>
				<nextPage>
https://<server>/unifiedconfig/config/attribute?sort=name%20asc&startIndex=25&resultsPerPage=25
				</nextPage>
				<resultsPerPage>25</resultsPerPage>
				<sortTerm>name asc</sortTerm>
				<startIndex>0</startIndex>
				<totalResults>10000</totalResults>
		</pageInfo>
		<attributes>
				<attribute>
								<changeStamp>1</changeStamp>
								<refURL>/unifiedconfig/config/attribute/5000</refURL>
								<dataType>4</dataType>
								<defaultValue>1</defaultValue>
								<description>XXXXY</description>
								<name>Att.00001</name>
				</attribute>
				<attribute>
								<changeStamp>0</changeStamp>
								<refURL>/unifiedconfig/config/attribute/5001</refURL>
								<dataType>4</dataType>
								<defaultValue>1</defaultValue>
								<description>XXXXX</description>
								<name>Att.00002</name>
					</attribute>
					<attribute>
								<changeStamp>0</changeStamp>
								<refURL>/unifiedconfig/config/attribute/5002</refURL>
								<dataType>4</dataType>
								<defaultValue>1</defaultValue>
								<description>XXXXX</description>
								<name>Att.00003</name>
					</attribute>
					<attribute>
								<changeStamp>0</changeStamp>
								<refURL>/unifiedconfig/config/attribute/5003</refURL>
								<dataType>4</dataType>
								<defaultValue>1</defaultValue>
								<description>XXXXX</description>
								<name>Att.00004</name>
						</attribute>
		</attributes>
</results>

Exceptions

See 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

See 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:

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

And, the following XML content is returned:

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

Exceptions

See Exceptions.

Values

The table below shows the values for <progress> in the returned XML content:

Value	Description
IN_QUEUE	The request passed validation and capacity checks and was put on the queue.
IN_PROGRESS	The request has been taken off the queue and is being processed.

Use Case

For further explanation, this section provides four use cases.

Table 2 I) Create (success)

1) User sends an asynchronous request to create an Attribute.	Example request: https://<server>/unifiedconfig/config/attribute?async=true
2) System validates the request and puts it in queue and returns the following:	202 Accepted status with progress of IN_QUEUE; and with a URL in the location header that can be polled for further status information. Example URL for polling: https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
3) User polls the status using the provided URL:	https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
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 the Call Type was created successfully:	201 Created status with a refUrl of https://<server>/unifiedconfig/config/attribute/<id>

Table 3 II) Update (success)

1) User sends an asynchronous request to update an existing Attribute.	Example request: https:// <server>/unifiedconfig/config/attribute/<id>?async=true
2) System validates the request and puts it in queue and returns the following:	202 Accepted status with progress of IN_QUEUE; and with a URL in the location header that can be polled for further status information. Example URL for polling: https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
3) User polls the status using the provided URL:	https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
4) System returns a 200 OK status to indicate the Call Type was updated successfully.

Table 4 III) Delete (success)

1) User sends an asynchronous request to delete an existing Call Type object.	Example request: https://<server>/unifiedconfig/config/attribute/<id>?async=true
2) System validates the request and puts it in queue and returns the following:	202 Accepted status with progress of IN_QUEUE; and with a URL in the location header that can be polled for further status information. Example URL for polling: https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
3) User polls the status using the provided URL:	https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
4) System returns a 200 OK status to indicate the Attribute was deleted successfully.

Table 5 IV) Create (failure)

1) User sends an asynchronous request to create an Attribute.	Example request: https://<server>/unifiedconfig/config/attribute?async=true
2) System validates the request and puts it in queue and returns the following:	202 Accepted status with progress of IN_QUEUE; and with a URL in the location header that can be polled for further status information. Example URL for polling: https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
3) User polls the status using the provided URL:	https://<server>/unifiedconfig/config/asyncrequeststatus/<id>
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.