Subscriptions in ICWS provide a way for applications to be informed when changes to the Interaction Center system take place. Applications first express interest in a subscription by calling the PUT method on the desired subscription resource. Each subscription resource has an associated message that will be sent to the client application via the messaging channel. This associated message is documented in the "Response" section of the subscription resource documentation. Once interest in a subscription has been established, messages will begin to be delivered through the messaging channel. Subscriptions can be stopped by calling the DELETE method on the subscription resource.

Each API in ICWS describes the status codes that should be expected when using that API. The status codes that have a consistent meaning across all APIs are listed below with descriptions of their meanings.

400 - Bad Request

The 400 status code indicates the client issued an invalid request. This includes malformed requests, requests with data that does not match business logic rules, and other validation errors. The response body will include the details about why the request was rejected.

401 - Unauthorized

This will only be used when the client does not have a session or the session is no longer valid. It is used to indicate that the client needs to log on.

403 - Forbidden

This means that the client is logged on but is not able to perform the requested operation. This is most commonly associated with the enforcement of security rights or access control lists.

404 - Not Found

The 404 status code indicates that the requested resource does not exist. A common case where this is used is when specific resource in a collection does not exist (e.g. GET configuration/users/userThatDoesNotExist). This can also indicate that the server does not implement the API. Checking the version information (see Versioning) when connecting will allow client applications to refrain from making requests to resources that the server does not support.

410 - Gone

This status code is reserved for APIs that have been deprecated and removed. This will not be used when an item in a collection has been deleted, 404 instead will be used.

The HTTP status codes provide a broad classification of an error type, however many times it is useful to provide additional details about the particular error case. The errorId property provides the additional details and can be consumed programmatically for improved error handling in the client application. The message property on the error representations provides a string that is meant for user consumption and can be displayed to the user.

The error identifiers provided in the errorId property are constructed using a hierarchy of period-separated segments. This hierarchy allows for classes of errors to be handled in the same manner without having to handle each individual error identifier. Additionally it allows for the addition of more detailed error identifiers without breaking existing error handling. For example, client code that is handling error.foo will not break if a more detailed error.foo.bar error identifier is added.

In order to check an error identifier, a 'prefix match' must be performed. An error identifier matches a prefix value if every segment in the prefix value is equal to the corresponding segment in the error identifier starting from the first segment in the error identifier. This match takes into account the entire segment when matching, so error.f does not match error.foo.bar but error.foo does.

The following JavaScript code provides an example function to match error identifiers:

function isMatch(prefix, errorId) {
    if (errorId === prefix) {
        // the prefix is a match if it is an exact match to the errorId 
        return true;
    }
    if (errorId.indexOf(prefix + '.') === 0) {
        // the prefix is a match if the errorId starts with the prefix followed 
        // by the period character to ensure the entire segment was matched
        return true;
    }
    // the prefix is not a match
    return false;
}

Enumerations (enums), as in many common programming languages, are distinct value types each represented by a set of named constants. In JSON, the enum values are represented as numbers by their integer values. The following is an example of the documentation and associated example JSON showing the enumeration licenseStatus.

{
    "licenseOperationResultList": [
        {
            "licenseName": "<License 1>",
            "isAvailable": true,
            "licenseStatus": 2,
            "errorDetails": ""
        }
    ]
}

In this example, the value of 2 indicates that the licenseStatus is available.

var Colors = {
    RED: 1,
    GREEN: 2,
    BLUE: 4
};