API Developers reference

1. API Concepts and Technical Overview

1.1 URLs and versioning

All requests to the API are made over HTTP. Your system administrator will be able to provide you with the base URL to use for the API, for example [https://api.mycompany.net/].Resources are versioned to ensure a stable interface is available for developers while allowing breaking changes to be made in future versions. All requests to the API must include the target version in the URL; at present the only version permitted is v1. Thus, with the above base URL, a request to the /Channels resource on the Collaboration service would be made to https://api.mycompany.net/Collaboration/v1/Channels

1.1.1 Format of request and response to the API

A developer may choose the format of the request or response to the API by setting the HTTP request headers “Accept” and “Content-Type” to “application/json” or “application/xml” for JSON and XML respectively.

1.2 Channels

The API introduces a concept of channels – a source and/or destination for messages. A channel may represent a chat room, an individual user, or (in future versions of the API) more esoteric data sources such as RSS feeds or e-mail accounts.Channels have a unique ID which is used to refer to them throughout the API. Each ID has a prefix indicating the underlying transport that the channel represents. At present these prefixes are:

  • chat-room: - for channels representing chat rooms

  • contact: - for channels representing an IM with an individual contact

It is recommended that, where possible, API users avoid depending on these prefixes and instead rely on proper provisioning of channels (see 1.3.2) and administrator-supplied configuration via meta-data (see 1.3.3).

1.3. Agents

An agent is the API’s representation of a single consumer of its services. The API maintains connections to underlying chat or collaboration systems on behalf of each configured agent. Agents have an ID defined by the administrator, which users of the API must be given in order to successfully authenticate (see 1.4).

1.3.1 Access Control

There are three distinct use cases intended for the API: System, Self and none

System provisioning acts like the existing provisioning mechanism, agents with System-level provisioning can add/update/delete anything

Self Self provisioning allows an agent to only update their own channels and metadata. Standard agents are limited to the authentication and collaboration APIs (see sections 2 and 3)

None disallows the agent from performing any provisioning

1.3.2 Provisioned channels

The API gives control of which channels an agent is allowed to communicate with to the system administrator, rather than the agent developers. Administrators must provision an agent before it is used, and in doing so must specify the channel(s) the agent is allowed to access.Agents can retrieve the list of their provisioned channels by accessing the /Channels resource. Administrators or advanced agents can update this list using the /Agents/{agentId}/Channels/{channelId} resource.

If an agent attempts to interact with a channel which they are not provisioned on, an error will be returned from the API.

1.3.3 Meta-data

Each agent has a ‘meta-data’ dictionary defined by the administrator. This is intended to allow agents to be configured through the API instead of through other means.

Administrators or advanced agents can modify the meta-data via the /Agents/{agentId}/MetaData resource.

Agents can retrieve their own meta-data via the Collaboration API’s /MetaData resource. The meta-data dictionary consists of a set of key/value pairs. Both keys and values are stored and transmitted as strings. There is no constraint on the content of keys or values, except that keys must be unique within each meta-data dictionary (as per a Java Map or C# Dictionary).

1.4. Authentication

In order to use the collaboration or provisioning APIs, callers must first authenticate as a registered user of the API, and supply the ID of an agent that they are provisioned to use.Upon successful authentication a token is returned, and this should be passed whenever a request is made to the Collaboration or Provisioning APIs. Tokens will expire after a period of time, and agents will need to re-authenticate in order to obtain a new one.

1.4.1 Creating a token

Tokens are created by making a POST request to the /Tokens/ resource. On successful authentication, a token will be returned. Information about the token (including the expiry date) can be retrieved from the /Tokens/{token} resource. While the expiry date is published, it is recommended that users do not schedule reauthentication, but instead rely on return codes issued by API methods. A typical workflow for making a request would therefore be:

  1. Check if a token has been previously retrieveda - If not, authenticate
  2. Request the resource with the previously obtained token
  3. Check the response code retrieved from the API - If 401 (not authorised): re-authenticate and go back to step 2.

1.4.2 Passing tokens

When calling Collaboration or Provisioning API methods, a valid token must be given in an Authorization header. The type of authorization should be ‘FCF’. A token of ‘abc123’ would therefore result in the following header being sent on all requests: Authorization: FCF abc123

1.5. Notation used in documentation

This section describes some of the notation used in the API documentation which follows.

1.5.1 Arguments lists

Arguments presented with a name in braces (for example {id}) are given as part of the URL when making the request.

Arguments presented with a name in angle brackets (for example ) are supplied as the entire body of the request – that is, they are not referred to by name.