Flattr Developer Platform

REST API v2

Documentation for the second iteration of our REST API

This API is newly released and is still in beta. We want your feedback on it to make sure we got everything right and may do some breaking changes where we realize we have made bad design decisions.

Basics

All resource paths are relative to the API-endpoint.

Create a application

To use the API you need to register a application and use the assigned Client ID and Client Secret. Client Secrets should be kept secret and not be revealed to anyone else than the application owner.

Authorization

To gain access to private data we use OAuth 2 for authentication. OAuth 2 is a standardized protocol for how to allow end users to authorize clients to gain access to their private data in the form of access tokens. OAuth 2 rely on separate standards for the access tokens - we currently use Bearer tokens which are the simplest and most widespread token type.

Authenticate

To get a token you need to use the authorization code flow.

(Extra line breaks are for display purposes only)

GET https://flattr.com/oauth/authorize?response_type=code&
client_id=1234&
redirect_uri=http://localhost

If the end user authorize your application the user will be redirect to your specified redirect_uri which must be in the callback_domain you specified when you registered your app at https://flattr.com/apps/new along side with a parameter named code whom you can exchange for an access token.

Request an access token

To get hold of a access token you need to exchange your code for a working token.

POST the code to the token endpoint and authorize using BASIC Auth created from your client_id and client_secret ( more information in RFC2617)

Access token request

POST https://flattr.com/oauth/token

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
  "code": "un8Vzv7pNMXNuAQY3uRgjYfM4V3Feirz",
  "grant_type": "authorization_code",
  "redirect_uri": "http://localhost"
}
Content-Type: application/json; charset=utf-8
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store
Pragma: no-cache
{
  "access_token": "8843d7f92416211de9ebb963ff4ce28125932878",
  "token_type": "bearer"
}

Hurray! you now have an access_token whom you can use to access the resources.

Including token in request

Include the access_token in the header when accessing the resources to authorize. More information is available in oauth bearer token draft.

Authorization: Bearer 8843d7f92416211de9ebb963ff4ce28125932878

Scopes

Available scopes

You can request several scopes when authorizing a user by separating them with spaces .

Example
GET https://flattr.com/oauth/authorize?response_type=code&
client_id=1234&
redirect_uri=http://localhost&
scope=flattr%20thing

Client errors

When a client side error occur you will get appropriete HTTP status code and a body with information about the error.

Example request
GET https://api.flattr.com/rest/v2/things/nothing_here
Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "error": "not_found",
  "error_description": "The resource was not found",
  "error_uri": "https://developers.flattr.net/api"
}

Response Formats

Activity Streams feeds are available for some resource, like flattr, things and activities.

Default response format is application/json.

You can specify another response format through the Accept header as specified in rfc2616 OR by adding a suffix for the file format to the URL (ex. categories.xml).

JSONP is supported by specifying a callback using the jsonp query parameter. The API also supports CORS, cross-origin resource sharing, for all requests – so JSONP shouldn't be needed in most modern browsers.

When using POST, PATCH or PUT application/json and application/x-www-form-urlencoded are valid formats of the request's own content.

Rate limiting

Four headers regarding rate limit is sent in all responses where rate limit is applied.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939

X-RateLimit-Limit - Current rate limit.
X-RateLimit-Remaining - Requests left during the current period.
X-RateLimit-Current - Requests you have made during the current period.
X-RateLimit-Reset - When your period ends you get new request. It's a unix timestamp.

When you exceed your rate limit a rate_limit_exceeded error will be returned on all rate limited resources. Your requests are reset every hour.

There is also a resourse where you can check the current rate limit (this resource is not rate limited).

Example request
GET https://api.flattr.com/rest/v2/rate_limit
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
  "hourly_limit": 1000,
  "remaining_hits": 986,
  "current_hits": 14,
  "reset_time_in_seconds": 1342521939,
  "reset_time": "Tue, 17 Jul 2012 10:45:39 +0000 GMT"
}
Visit Flattr.com to learn more about Flattr.