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.

Table of Contents [Hide/Show]

Usage
Status codes
Resources
Authentication and access control
Support for limited clients
API Throttle
Example clients
External resources

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:

200 OK
This is the standard response given on successful requests, reguardless of HTTML method used.
204 OK, but No Content
The server successfully processed the request, but is not returning any content. In our API this is typically used in PUT and DELETE requests, when we don't see a need for returning any updated data.
400 Bad Request
This will usually be returned if the request does not make sense to us, and we are unable to perform the action. Typically it's used when the data sent in a POST or PUT is invalid.
404 Not Found
The requested resource could not be found. Typically you have requested an element by id, but that element either does not exist or is not accessible to your user. Or you have simply requested an endpoint that does not exist.
405 Method Not Allowed
Could be a result of accessing an endpoint like /contacs/{id}, but using a string (text) as the id instead of a number (integer).
406 Not Acceptable
This status will be returned if authentication or authorization fails. It can also be returned for some undefined exceptions. For exmaple if the parameters are wrong, or in wrong case (parameters are Case-Sensitive).
500 Internal Server Error
Some unforeseen error happened on the server.

Resources¶

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

User - read-only data about the current user, including organization information and settings.
Contacts - complete administration of contacts, including search.
Groups - complete administration of groups, and the contacts therein.
Messages - get, delete and send SMS messages.
Folders - read-only access to folder tree and messages in folder.

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.

Regular .NET client - This client code uses plain vanilla C# code, and no extra dependencies.
Hammock client - Hammock is a REST library for .NET that greatly simplifies consuming and wrapping RESTful services.
Clojure client - Clojure is a language in the Lisp family running on the JVM. There is also a clojure client library hosted on github which you can use to access the API.

External resources¶

When experimenting with the API you could also benefit from using a command line tool like curl, which will let you do ad-hoc REST request with basic authentication and different http methods.
Blogpost about consuming the Intouch REST API from Node.js (in Norwegian).