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.

Rate limiting

Two headers regarding limit is sent in every response.

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

X-RateLimit-Limit: is the current max requests. X-RateLimit-Remaining is how many requests you have left until you are blocked temporary. When that happens, a ratelimitexceeded error will be returned. Your remaining requests are reseted automatically every hour certain intervall.

Authorization

To gain access to private data clients need to use OAuth 2. 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.

To use OAuth 2 you need to register their 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.

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 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
Status: 404 Not Found
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "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.

Visit Flattr.com to learn more about Flattr.