TickTocker API Documentation

eric - October 31st, 2010

Current Version: 1.0

The TickTocker API is an application programming interface that allows developers to extend the TickTocker platform into their own apps and websites. In version 1.0, developers are able to create applications that interface with the TickTocker website and create events, follow other users, view tock streams, and more. All communication with the TickTocker API occurs over encrypted SSL so it is secure. TickTocker API function calls are done over HTTP and require specific POSTed data to function. All return values are in JSON for version 1.0. This is the documentation on how to leverage the TickTocker API.

This API is developed for developers so if there is anything you don't like about it, please let us know by contacting us at email. We have created an online API Testing Utility for registered TickTocker users.

Definitions and Caveats

TickTocker.com - This website. The API responder can also be considered and is sometimes referred to as TickTocker.com.

Client - The application connecting to TickTocker on behalf of a specific user.

Tock - An event created by a user and saved in the TickTocker database.

Tock Stream - When more than one Tock is returned in an array, it's called a tock stream. Tock streams contain slightly less information about each tock than a single Tock lookup would return.

Application Token - A unique ID given to your application by TickTocker.com that identifies it with the TickTocker service. Application Tokens are given out to verified users who agree to a separate Terms of Use document regarding the TickTocker API. The service to request an application token is currently offline but to request one please email us email.

API Key - A unique ID each user has built into their account that is used to sign commands with the system. Developers should store this token securely as it grants access to a user's account similarly to their password. This token is changed when a user changes their password.

Endpoint - The current version of the API is 1.0 and as such the current endpoint is https://ticktocker.com/api/1/ Due to the evolving nature of this document, endpoint may be abbreviated as [ep]. Substitute the actual endpoint URI for to get a full function call. While there may be updates with version 1.0, the endpoint will always remain ~/1 and future major versions will likely be at ~/2, ~/3 etc.

Rate Throttling - Currently commands are throttled at a rate of one command every 200 milliseconds. Users also get 120 commands per hour. These are replenished at a rate of 2 every minute. These rates are subject to change depending on API usage.

Authentication

To authenticate, clients must retrieve an API token for a specific user from TickTocker.com. To obtain the API token, you must HTTP POST the user's login and password to [ep]/getapikey in the form u=[username]&p=[password]. TickTocker.com will respond with a JSON object that looks similar to the following:

{
    "code":1,
    "response":
    {
        "username":"gadgets",
        "name":"Gadgets McGee",
        "url":"gadgets",
        "timezone":"America/New_York",
        "avatar":"http://ticktocker.com/images/fbsecure/gadgets.jpg",
        "apikey":"[long api key]"
    }
}

The API key that is returned is the token you will be posting along with username and your application token with every function call. This function may also return code -4 API_FAIL_BAD_APP, which means that the application token has been invalidated.

General Function Calls

All function calls are performed similarly. You must post username, apikey, and application token with each call in the format: u=[username]&t=[apikey]&a=[application token]. Some functions require parameters to be set in the URL. The response returned by the server is a JSON object that has two first level items. The second value is result, which can contain data specific to the request. The first value is code, which describes the result code of the operation. It has several values each with a specific meaning. Your application must respond to each code properly and any function may respond with any value.

Function Responses

API_OK = 1

The function finished OK.

API_NONE = 0
The command completed but there was no response was returned from the server. This could be because you are missing a parameter to a function. You may have a value of error in response that may contain a human readable error message.

API_FAIL = -1
Either invalid data was input or a function simply failed.

API_FAIL_NO_LOGIN = -2
User is not successfully logged in. This could also mean their API key has been invalidated or the application token has been invalidated.

API_FAIL_NO_AUTH = -3
User is logged in but does not have sufficient privileges to run the requested function. If a user is banned their authorization level will cause this error to trigger.

API_FAIL_BAD_APP = -4
The application token provided is invalid.

API_FAIL_TOO_FAST = -5
The command was attempted too quickly after a previous command. Make sure your application abides by throttling rules.

API_FAIL_NO_MORE_CALLS = -6
The user has no more API calls allowed. Make sure your application abides by throttling rules.

Available Functions

Parameters listed are passed through the URL. Requirements are variables POSTed to the function. Please read Endpoint under Definitions and Caveats and Authentication for more information.

Parameters are listed in pseudo-regular expression syntax. [ep] of course can be replaced with the endpoint. Where you see parameter lists in parens (), it means one of the piped items must be present in the request. Parameters listed in curly braces {} are optional. Parameters that are surrounded by square brackets [] are required input from you that is typically returned from a request elsewhere.

[ep]/getapikey

Parameters: none
Requires: u,p,a

See Authentication for more information.

[ep]/version

Parameters: none
Requires: u,t,a

To get the current version and the amount of API calls a user has left, you can call this function. Below is sample output:

{
    "code":1,
    "response":
    {
        "api_version":1,
        "logged_in":true,
        "application":"TickTocker.com Development Environment",
        "calls":120
    }
}

Querying the endpoint without a function will also trigger this function. This is the only place where two URL's will trigger the same function.

[ep]/tock

Parameters: [ep]/tock/[short_url]
Requires: u,t,a

This function retrieves specific information about a tock in the system. Short_url is a field that is returned in a tock stream.The returned data includes information about the tock, start and end times in UTC time, the timezone it was created in, URL construction information, user interaction data, and author information.

Sample response: [ep]/tock/8c866

{
    "code":1,
    "response":{
        "tock":{
            "title":"Time since last beat missed.",
            "description":"The SMS conception.",
            "event_start":"2010-04-14 17:05:00",
            "event_end":"2010-04-14 18:05:00",
            "timezone":"America/New_York",
            "short_url":"8c866",
            "url":"time-since-last-beat-missed",
            "upvotes":2,
            "dnvotes":0,
            "event_created":"2010-07-16 19:02:34",
            "tags":"site, ticktocker",
            "repeat_frequency":"no",
            "num_comments":1,
            "private":0,
            "link":"http://ticktocker.com/",
            "location":"",
            "upvoted":1,
            "dnvoted":0,
            "watched":0,
            "author":"eric",
            "author_avatar":"http://graph.facebook.com/FBID/picture",
            "author_url":"eric",
            "invited":0,
            "author_followed":0
        }
    }
}

To construct a url to this tock you can either concatenate 'http://ticktocker.com/' + author_url + '/' + url or use the built-in URL shortener 'http://tcktck.com/' + short_url (which will redirect the browser to the proper url).

[ep]/follow

Parameters: [ep]/follow/[user_url]
Requires: u,t,a

This function allows you to follow or unfollow a user. The user_url parameter must be the user's url and not their username. All tocks return both author name and author url. These may be similar in most cases but can be different.

[ep]/community

Parameters: [ep]/follow/(hot|fresh|upcoming|history)/{page}
Requires: u,t,a

This function returns a tock stream relating to the major community feeds.

[ep]/me

Parameters: [ep]/me/(all|mine|watched|liked|followed)/(upcoming|latest|expired)/{page}
Requires: u,t,a

This function returns a tock stream relating to the currently logged in user's tocks.

[ep]/user

Parameters: [ep]/user/[user_url]/(upcoming|latest|expired)/{page}
Requires: u,t,a

This returns the requested tock stream of the specified user by user_url.

[ep]/submit

Parameters: [ep]/submit
Requires: u,t,a,title,evenstart

This function allows users to submit tocks via the API. Data about the tock must be posted along with the standard user, token, and application post. Upon successful creation of a tock, the tock's short_url is returned in the response.

The following variables are allowed:

Tocks submitted via API will show a link to the App they are submitted by when viewed on TickTocker.com

Conclusion

Please email us with anything you don't like about the API and we will see about fixing it in the next revision or major version. Depending on developer interest and strategic importance, we plan on adding commenting, upvoting, downvoting, and enhanced tock querying capabilities to the API.