Collaborating
Applications themselves will be written against the Collaboration service. This service uses Channels and Messages resource collections to model the channels on the underling system. More information about writing applications against this service can be found in the developer guide.
10.1 Authorization
Requests to the collaboration service are mapped directly to and serviced by the agent contained in the provided token. Hence, tokens used to access the collaboration service must be issued for an agent – i.e. tokens issued for the super user account will not be accepted.
Furthermore, the agent mapping to the account must be “active” – i.e. logged in to the system. Calls made with a token whose agent is not active will be failed with a Service Unavailable code. Applications must be written to deal with this error code as this will occur when the connection to the underlying chat system is dropped. Note that reconnection of the agent is automatically performed inside the MindLink API, so external application code should gracefully fail as appropriate and then retry until the agent becomes active again.
10.2 Event Streaming
Applications perform invocation and query operations on the chat system e.g. message sending, message fetching using standard HTTP verb requests - e.g. GET/POST etc. - since this paradigm is a natural mapping. To be able to subscribe to and wait for remote events e.g. receiving messages, we must use a different mechanism.
We have chosen to solve this by using a long-polling (sometimes known as “Comet”) pattern, whereby the application should continually make HTTP GET requests to the Events resource collection. If new events are available then the request will return immediately with those events, otherwise the request will be held open until events become available. If no events become available within 30 seconds an empty collection of events is returned.
Typically this logic will be implemented in an application in the form of a loop that continually makes a request, processes each event in the returned response (which may be an empty set of events), and then makes the request again.
The types of events that are returned can be configured via the querystring – this provides a pseudosubscription mechanism.
Note that when addressing the resource using instanceIDs, requests will fail if the ID does not match the API service instance. If this should occur, steps should be taken to re-synchronize the ID to continue long-polling (see section 3.8.5).
Sample Code Repository
Sample code can be downloaded from https://github.com/mindlink/api-samples