REST API version 1.0

Coffeestats provides a small REST API to be used by third party applications. The API is described with some example curl calls below.

Base URI

The API is hosted at /api/v1/ and provides several resources that are described in detail below.

curl https://coffeestats.org/api/v1/$Resource

Authentication

The username and the user’s on-the-run token are used for API call authentication. You can see both used as GET parameters for the bookmarkable on-the-run link on you profile page.

curl -X POST -d "u=user&t=yourtokenhere" https://coffeestats.org/api/v1/$Resource

This is an incomplete example. See below for detailed resource descriptions.

Resources

random-users

POST /api/v1/random-users

Query a set of random users

Form Parameters:
 
  • u – user name
  • t – on-the-run token
  • count – optional number of users
Response Headers:
 
Status Codes:
  • 200 OK – all is ok, body contains a list of users
  • 403 Forbidden – authentication required

curl example

curl -X POST -d "u=user&t=yourtokenhere" https://coffeestats.org/api/v1/random-users |python -mjson.tool
[
  {
    "coffees": "42",
    "location": "baz",
    "mate": "0",
    "name": "foobar",
    "profile": "https://coffeestats.org/profile?u=foobar",
    "username": "foobar"
  },
  ...
]

add-drink

POST /api/v1/add-drink

Submit the consumption of a drink (mate or coffee)

Form Parameters:
 
  • u – user name
  • t – on-the-run token
  • beveragemate or coffee
  • time – timestamp in a format with ISO 8601 date and time i.e. 2014-02-24 19:46:30
Response Headers:
 

curl example

curl -X POST -d "u=user&t=yourtokenhere&beverage=mate&time=2014-02-24 19:46:30" https://coffeestats.org/api/v1/add-drink |python -mjson.tool
{
  "success": true
}