API Concepts And Technical Overview

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 Categories#

The API utilises the concept of categories – a container for chat rooms. A category defines the available features, the allowable users and the accessible roles for chat rooms within the category. Categories are managed by a chat system administrator and cannot be modified through the API.

Categories have a unique ID which is used to refer to them throughout the API. Each ID has a prefix:

  • category: {CategoryId}

1.4. 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.4.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.4.2 Management Access Control#

There are two distinct use cases for Channel Management: Group and None

Group allows the Agent to leverage channel management functionality for the chat room(s) that it manages.

None prevents the Agent from leveraging channel management functionality.

1.4.3 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.4.4 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.5 Channel Management#

API Agents can be provisioned for channel management, determining the agents ability to leverage management functionality. When provisioned, Agents can GET the details of the channels that they manage, can return the membership list of a managed chat room, set the members of a managed chat room, create chat rooms and delete chat rooms that they manage.

If the Agent is not provisioned for channel management, attempting to leverage the functionality will return an error.

An Agent can GET or SET members of a channel they manage. Channel membership is specified in terms of the underlying chat system identities and not API identities. This effectively means that in a Skype for Business deployment members can be user SIP addresses or Active Directory Groups or Organizational Units:

  • sip:user@domain.com - specifies a user by their SIP address
  • resource:CN=common,OU=ou,DC=domain,DC=local - specifies an Active Directory resource

If an Agent attempts to GET or SET members for a room they do not manage an error will be returned.


1.5. 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.5.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 retrieved - 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.5.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.6. Notation used in documentation#

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

1.6.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.


Sample Code Repository#

Sample code can be downloaded from https://github.com/mindlink/api-samples