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: - Content-Type – text/json
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
- beverage –
mate
orcoffee
- time – timestamp in a format with ISO 8601 date and time i.e. 2014-02-24 19:46:30
Response Headers: - Content-Type – text/json
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
}