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
Requests and response bodies are written in standard MIME (media) types. By default the API will respond to requests in JSON (application/json), and this is the format that we would recommend developers use.
Requests to the API should have their Content-Type header specified to be considered valid. Specifying Content-Type as application/json and using JSON formatted request bodies (where necessary) is strongly recommended.
If necessary it is possible to specify that API responses are formatted in xml by setting the Accept header to application/xml. Similarly, request bodies can be formatted in xml if Content-Type is set to application/xml.
However, we intend to deprecate support for xml as a request or response MIME type in a future version of the MindLink API. So we would recommend, when writing any new applications or scripts, to use JSON as the transport MIME type when targeting the MindLink API.
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:
- Check if a token has been previously retrieved - If not, authenticate
- Request the resource with the previously obtained token
- 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