Flattr Developer Platform

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

• API-endpoint: https://api.flattr.com/rest/v2
• OAuth 2 authorization: https://flattr.com/oauth/authorize
• OAuth 2 token: https://flattr.com/oauth/token

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.

• response_type ( Required ) - This can be set to code or token
• client_id ( Required ) - The client_id found at http://flattr.com/apps
• redirect_uri ( Optional ) - The callback URL supplied when creating the application. It needs to be identical or else the authentication will fail.
• scope ( Optional ) - Available scopes Separate scopes with spaces.

(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)

• code ( Required ) - The code you received from authorization endpoint
• grant_type ( Required ) - Set to authorization\_code
• redirect_uri ( Required ) - Your applications callback URL

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

• flattr - Flattr things
• thing - Create, update and delete things
• email - Read the users email address
• extendedread - Read private user attributes and find hidden things

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.

• invalid_request (400 Bad Request) - Not a valid request
• invalid_parameters (400 Bad Request) - Parameter missing or invalid
• unauthorized (401 Unauthorized) - Unauthorized to access resource
• rate_limit_exceeded (403 Forbidden) - To many request the last hour
• invalid_scope (403 Forbidden) - Scope does not exist
• insufficient_scope (403 Forbidden) - Don't have the scope required to access resource
• not_found (404 Not Found) - Resource was not found
• not_acceptable (406 Not acceptable) - Unknown response format

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

• application/json - .json ( Default )
• text/xml - .xml
• application/yaml - .yaml

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

• application/stream+json - .as - defined in this specification
• application/atom+xml - .atom - defined in this specification

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.