Over the past few weeks I have been helping Curverider develop the next generation of Elgg products, the first of which to be released is elggVoices – a cross platform short messaging tool.

One of the key features of elggVoices which I have been heavily involved in developing is a powerful and fully featured API. This API lets you read and post messages (shouts), search for channels, find all shouts on a given subject etc.

Getting the resources

Over the next few weeks we will be building this out with example code, client libraries etc. The first step is to get yourself over to the developer centre and take a look at the resources available. At the very least you should download the API documentation, this explains what API calls are available and what parameters they take.

API Keys

In order to be able to use the API, you will require two keys – a public API key, and a secret key. To obtain your keys, you can sign up for some at the developer centre.

The public API key is a way to identify your client with the elggVoices server, while the secret key is used to sign your api call and should be kept safe.

Making an API call

Once you have got your keys, you can begin making elggVoices API calls by using the REST endpoint at:

http://elggvoices.com/api/v1/

By far the easiest way to do this is to use one of the client libraries, however in the event a library hasn’t been written for your preferred language (or you fancy writing one), you are going to have to construct a raw query, as follows…

An API call is either a GET or a POST request, with API variables passed as a URL encoded string on the GET line. The POST data should be used for queries which expect large data blocks (file transfer etc).
An example api call might look like this:

http://elggvoices.com/api/v1/?method=example.method&format=xml&foovar=bar

Where method is the method call you are making, and format is the desired reply format (xml,php,json). These required variables can then be followed by an arbitrary list of other parameters expected by the API call.

Tomorrow I will show you how to construct a HTTP request using custom request headers, and to construct the all important HMAC signature.