Intouch REST API version 1

Modified on Thu, 16 Nov 2017 12:18 by Audun Hegranes — Categorized as: Uncategorized

Version 1 of the Intouch API is deprecated and will not be developed further. From 2014.01.01, all customers should use version 2 

The Intouch API provides a simple yet powerful interface to the central features of the PSWinCom Intouch product. It can be used to automate tasks like synchronizing contacts, facilitate custom SMS services, or even implement alternative user interfaces.

The API is a REST-interface. It's “firewall-friendly” since it's running over the standard HTTP protocol and port number 80 is used for client connections. For data transfer it supports both XML and json.

The deprecated version 1 of the API can be found at http://intouchapi.pswin.com/1/. Fore more information about the current version, see Intouch Rest API version 2.

Usage



Status codes

HTTP status codes are used to give callers information about the result of API requests. In particular the following codes should be expected:


Resources

The API can be divided into several top-level resources, which are:


Authentication and access control

Use of the API is always through an existing Intouch user account. There’s no special API user. You get to see and work with what the user you are logging in to the API is allowed to. To use the API you’re required to add user credentials via HTTP Basic Access Authentication. In addition your user account or organization must have the API feature enabled. If it's not you will have to contact PSWinCom Support by email to enable it.

Using plain HTTP should be done with caution when dealing with information. All data are sent as clear text over the Internet and may be intercepted by a third-party. To increase security, the SSL secured transport layer (HTTPS) can be used. See SSL certificates for details.

When authenticating through Basic Authentication the username should be constructed from your Intouch username and your Intouch domain. Here's an example

Intouch user: MrJohnson
Intouch domain: acme.com
Intouch password: abc123

Username to be used in authentication: MrJohnson@acme.com
Complete authentication token before encoding: MrJohnson@acme.com:abc123

The base-64 encoded value of the token is used in the request header. See the example clients for more details on how to implement the authentication.



Support for limited clients

Clients implemented in technologies unable to use REST methods like PUT and DELETE (e.g. FLASH) can still utilize the full Intouch API. To do so the client has to use the POST method while adding the special X-HTTP-Method-Override header to the requests. For a PUT operation the header should be:

X-HTTP-Method-Override:PUT

API Throttle

To ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain threshold in terms of a maximum of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a HTTP 503 response code and a text body of “Number of allowed API requests per minute exceeded”

We encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).

Example clients

We have implemented some sample clients to give you an idea of how to use the API. Unless otherwise noted, all source code referenced below is public domain, and may be freely distributed, modified, and used for any purpose. IT COMES WITH ABSOLUTELY NO WARRANTY OF ANY KIND.


External resources