Return Values

All API methods return a result for the operation in addition to the HTTP status code. The results are different depending on the type of operation. Except as noted, the results will be as follows:

All Methods

All methods will ALWAYS return the attribute statusCode and, if an error has occurred, statusMessage on the top level of the response. The following status codes are supported:

Code	Description
0	The operation is successful. No statusMessage is provided.
1	A required parameter is missing in the request.
2	A specified parameter is not valid for the current state.
3	The operation is forbidden.
4	An internal error occurred. This might happen if an internal error occurred with Web Services or with one of the servers working with Web Services (such as Cassandra or a Genesys Framework component).
5	The user does not have permission to perform this operation.
6	The requested resource could not be found.

If an error occurred during an operation, the response includes statusCode and statusMessage clarifying the error No other attributes will be included.

Note that if an error occurs during a request, with you can assume that the request failed to modify the data of the contact center.

GET

GET requests are used to retrieve a variety of information. The response body will depend on the requested and the request parameters. These are the possible scenarios:

1. If retrieving a collection of URI's, the response will include the array attribute "uris" which will hold the requested collection.

2. If retrieving a collection of resources, the response will include an array attribute named after the requested resource. For example, GET /users?fields=* will contain "users":[ {..user1..}, {...user2...}, etc].

3. If the URI is a "singular" resource such as GET /users/{id}, the response will include an attribute named after the singular of the requested resource which will contain the requested value. GET /users/{id} will return "user":{...user..}.

Examples

GET /skills

{
      "statusCode":0,
      "uris":["http://../api/v2/skills/123", "http://../api/v2/skills/456", etc]  
}

GET /users?fields=*

{

    "statusCode":0,
    "users":[{"userName":"..", "firstName":"...", etc}, {"userName":"..", "firstName":"...", etc}]  


}

POST to Create Resource

When a POST request is successful, the following extra attributes will be included:

1. id—the ID of the newly-created object.

2. uri—the URI to access the newly-created object.

Examples

Request:

POST /users
{
 ... some user data
}

Response:

{
    "statusCode":0
    "id":"12345",
    "uri":"http://...api/v2/users/12345"
}

POST to Assign Resource

POST can also be used to assign one resource to another's collection such as when assigning a skill to a user. When this is the case, no extra attributes are returned and only statusCode:0 will be returned on success.

DELETE

The DELETE operation does not have any extra attributes. Only statusCode:0 will be returned on success.

DELETE to Unassign Resource

DELETE can also be used to unassign one resource from another's collection such as when unassigning a skill from a user. No extra attributes are returned and only statusCode:0 will be returned on success.

PUT

The PUT operation does not have any extra attributes. Only statusCode:0 will be returned on success.

Asynchronous Operations

Web Services supports many operations that are performed using POST on an existing resource and the response for which is sent via CometD. When POST is used to perform one of these operations, statusCode:0 will be returned on success.

Hybrid Operations

In order to increase API usability and minimize network traffic, multi-step operations are occasionally implemented. For instance, it is possible to create a device and assign it to a user with one operation. When hybrid operations are implemented, the methods will return all of the values required for each operation being performed. For example, POST to create a resource requires a return value of "uri" and "id" whereas POST to assign does not have any extra return values. Implementing a multi-step "create and assign" POST returns "uri", "id", and "statusCode" on successful completion.