Documentation Conventions

The ICWS documentation contains many conventions and special indicators to describe the rich API. This section provides tips for how to read this documentation and how to interpret the associated JSON that the web service consumer code would use.

This topic contains the following sections:

Resource URIs

Most resources in ICWS are accessed via URIs that contain substitution points, or template substitutions. This allows documentation of a single resource URI that is parameterized to provide access to many specific resources. When a resource URI has a template substitution, the resource's request parameters will contain a parameter to describe the values that can be substituted into the resource URI template location to create a specific URI for use with ICWS. An example of this is GET /icws/{sessionId}/interactions/{interactionId} which contains template substitutions for both the sessionId and interactionId being requested.

Representation Objects

ICWS requests, responses, and messages have payloads described via "representation" objects. Representations are composed of properties, lists, dictionaries, and collections of properties (i.e. complex types). When a representation contains lists, dictionaries, or complex types, it is represented in the documentation as a collapsible tree of properties. This tree is a visual indication of the structure of the JSON that would be sent/received for that representation.

As an example, GET /icws/connection/features returns a response containing a list of feature/version pairs. The representation's documentation is shown below, followed by an example of the JSON that the web service consumer code would receive.

Example Representation Documentation
{
    "featureInfoList": [
        {
            "featureId": "<Feature 1>",
            "version": "1"
        },
        {
            "featureId": "<Feature 2>",
            "version": "5"
        },
        {
            "featureId": "<Feature 3>",
            "version": "2"
        }
    ]
}

Multiple Options

Some representations accept multiple sets of properties depending on the intended mode. In these cases, a special property __type (with two underscore characters) is used to specify which of the representation options is being used. An example request is POST /icws/connection which accepts multiple forms of authentication by providing the appropriate representation for the intended authentication method. Another example is the GET /icws/{sessionId}/messaging/messages response which contains a list of heterogeneous complex type objects, where each list item will have the __type property to indicate which complex type it is.

Recursive Representations

Some complex types can contain properties, possibly multiple levels of complex type objects deep, where the property is of the same type as the complex type itself. In JSON, this would result in a tree of deeply nested properties with whatever depth was appropriate for the operation being performed and the data it requires. In the ICWS documentation, this sort of recursive representation is indicated by a badge and not including all of the property's complex type's properties again.

Lists

Some representations can contain properties that are lists. These lists can be "unbounded" with 0 or more items, or they can be "bounded" with a minimum and/or maximum number of items in the list. The following example shows the documentation of an "unbounded" list that might contain any number of items, followed by an example of the associated JSON array. In this case the property is marked as , so it is always provided but might contain 0 items in the collection.

Example Unbounded List
{
    "items": [
        { /* Contents of complex object 'user'. */ },
        { /* Contents of complex object 'user'. */ },
        { /* Contents of complex object 'user'. */ }
    ]
}

Some lists are "bounded" with a minimum and/or maximum number of items. The following example shows the documentation of "bounded" lists that will contain at least one item, followed by an example of the associated JSON array. (Note that some unrelated properties were removed from this image for brevity.) In this case the properties are not marked as , so a particular list property might not be provided at all, but if it is provided then it should have at least one item in it.

Example Bounded List
{
    "__type": "urn:inin.com:configuration.people:usersMessage",
    "isDelta": "true",
    "subscriptionId": "<subscription ID>",
    "added": [
        { /* Contents of complex object 'user' removed for brevity. */ },
        { /* Contents of complex object 'user' removed for brevity. */ },
        { /* Contents of complex object 'user' removed for brevity. */ }
    ]
    "removed": [
        "<removed user ID 1>",
        "<removed user ID 2>"
    ]
}

Dictionary Complex Types

Some representations can contain properties that are dictionaries. In this case, the dictionary does not have explicitly defined properties in it; rather, it has a collection of properties defining name/value pairs. The following are examples of the documentation and associated example JSON for a dictionary.

Example Dictionary Complex Type
{
    "attributes": {
        "<Key 1>": "<Value 1>",
        "<Key 2>": "<Value 2>",
        "<Key 3>": "<Value 3>"
    }
}

User Interface Elements

In the ICWS documentation, there are some user interface elements that allow for interaction with the documentation display. This section describes those elements.

Badges

Throughout the ICWS documentation, a common convention is to mark certain key elements with "badges" to highlight something. This section describes the meaning of the various badges contained in the documentation.

BadgeDescription
In the documentation for resource requests, some optional parameters have default values when the property is not specified. This badge identifies these parameters and specifies the default value that will be used in the parameter's absence.
In the documentation for resource requests, the list of parameters includes HTTP header parameters which are marked with this badge.
In the documentation for resource requests, the list of parameters includes HTTP query parameters which are marked with this badge.
Most resource URIs in ICWS are parameterized with template substitution points. Specific values are provided at these points in order to form a particular resource URI for use. In the documentation for a resource, the list of parameters includes items marked with this badge to indicate template parameters. See Resource URIs for more detail.
In representations, if a property has a complex type that is the same as a complex type that it is defined in, the documentation will mark the property as recursive using this badge. See Recursive Representations for more detail.
In representations, if a property has an enumeration type that represents multiple simultaneous values, the documentation will mark the property as a bit flags enumeration using this badge. See Bit Flags Enumerations for more detail.
If a representation contains a property that is not optional, it will be indicated as required using this badge.
If a representation contains a property that is required, dependent on the value of a different property, it will be indicated as conditionally required using this badge. For example, a property could only be required if a different property is either missing, or set to a specific value. For these cases, additional documentation on the properties will indicate the cases in which a property will be required or not.

Controls

Representations have special controls for interacting with their property lists. The entire representation's property list can be expanded or collapsed (recursively) with the Expand All and Collapse All buttons and an individual property can be expanded or collapsed using the triangular chevron to its left. Additionally, the info button (labeled with "i") can be pressed to get additional documentation for the representation, when available. The following documentation example contains all of these elements.

Example Representation Controls

Another special documentation control is for long lists. With long lists, a toggle button is used to show the whole list or to hide it. This button is labeled Show More or Show Less depending on whether the list is currently expanded. The following documentation example shows this control.

Example List Controls

Versions

An application that uses the ICWS API might be run with servers of different versions. For an application to be well-formed it should verify that the server it connects with actually supports the API features that it requires. To support this, ICWS API methods document the Feature and feature Version that they require the server to support in order for the method to be invoked.

Example Version Documentation

A server's supported features can be requested using GET /icws/connection/features, which returns the supported features and the versions of those features, or GET /icws/connection/features/{featureId}, which returns the version for a specific feature. This can be compared with the documented Feature and feature Version that are required for a specified method, to allow programmatic behavior changes in the application when the required functionality is not available in the server that it is connected to.

For more information about versioning, see Versioning.

Note

These values only change when the server is updated, so an application can use caching strategies rather than repeatedly query the feature versions of the server.

Obsolete Versions

If an API element is no longer supported, the ICWS API documentation for that element will specify in which feature version it is obsolete.

Example Obsolete Version Documentation