API Documentation

Components

action	Log and query user actions.
category	Multi-purpose high level categories.
graph	Find nodes and traverse edges of the generated graph.
identity	Get indentity information for individuals.
item	Shareable units of information.
member	An authenticated user, usually part of one or more organizations.
organization	Creators of items. Trackers of clicks.
quota	Get information about quotas.
session	Manage user sessions.
url	Where it's at.

Making API Calls

Identifying Yourself

Next to every method in the API documentation is a description labeled "required identity". If it states "anonymous", you needn't do anything to identify yourself. If it states "organization_restricted", you must provide your organization key like so:

http://click.st/rest/some.method?key=__KEY__

If it states "organization", you must provide a signature. There are two types of signatures. One is for direct server-to-server communication. The other, called a user signature, uses an intermediate signing key called a request key. User signatures are valuable when you want to restrict communication to click.st to a single IP address.

About the nonce

Regardless of the signing method you choose, a nonce will need to be generated. There is no required format for a nonce but it should be unique to the request.

Simple Signatures

If you are able to communicate directly with click.st then use this method. Generating a signature is simple:

signature = sha1(concatenate(KEY, NONCE, SECRET))

A request will look like this:

http://click.st/rest/some.method?key=KEY&nonce=NONCE&signature=SIGNATURE

User Signatures

If you need to communicate with click.st via a third-party you don't trust with your secret (for instance a user's browser) then use a user signature. You must create a request key using the client's IP address and your secret:

request_key = sha1(concatentate(CLIENT_ADDRESS, SECRET))

Then create a signature like so:

signature = sha1(concatenate(request_key, nonce))

A request URL will look something like this:

http://click.st/rest/some.method?key=KEY&nonce=NONCE&user_signature=SIGNATURE

Note the name of the signature parameter. It's user_signature in this case not signature.

PHP Example:

Using REST

The REST endpoint is located at http://click.st/rest/. To construct a REST call, append the method name to the endpoint like so:

http://click.st/rest/action.count

Method parameters may be provided either in the query string or in the POST body as application/x-www-form-urlencoded data. Let's get a count of button clicks for last week as an example. First we need to construct our url. The method we want requires "organization" identity so it will look like this:

http://click.st/rest/action.count?secret=__SECRET__

Now let's create our POST body:

start=1327968000&
end=1328572800&
action=button.click

Some methods require passing objects or lists. For lists, use the parameter name followed by [] as many times as necessary. For example:

someparam[]=the-first-item&
someparam[]=the-second-item

For complex objects with nested fields use the field names within []. For example, this:

someparam = {
    foo: "bar",
    baz: 23,
    p: {
        x: 1.7,
        y: 2.35
    }
}

can be passed via the POST body like this:

someparam[foo]=bar&
someparam[baz]=23&
someparam[p][x]=1.7&
someparam[p][y]=2.35

The return value of a call is always a JSON document with the following form:

{
    result: <results-of-call>
}

or, in the case of an error:

{
    error: <error-message>
}

It is also possible to perform a JSONP call by passing the name of callback function in the query string. For example, this:

http://click.st/rest/some.method?__callback=foofn

will result in this:

foofn({ result: 'bar' })

Using JSON-RPC

The JSON-RPC endpoint is located at http://click.st/jsonrpc/. Constructing a URL for a JSON-RPC call is similar to constructing a URL for a REST call. You append your identity, if required, in exactly the same way but the path is the component part of your method call. For example, if you wanted to call action.count, the component is action and the method is count. The URL would look like this:

http://click.st/jsonrpc/some?secret=__SECRET__

You then pass the method part, in this case "count", as the method parameter in your JSON-RPC request. More details about JSON-RPC can be found in the JSON-RPC 1.1 Draft Specification. The click.st implementation is based on this draft however it differs in some important respects:

• GET requests are not supported,
• positional parameters are not supported,
• none of the system methods are implemented.

In other words, this implementation is very basic and supports the simple request and response cycle of the specification.