API:
Documentation

Overview

To use our API, you need to register your application and authenticate with either OAuth or your client access token when making requests.

Current Version
Schema
Parameters
HTTP Verbs
Authentication
Pagination
Rate Limiting
JSON-P Callbacks

Current Version

By default all request receive the v2 version API. We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.tookapic.v2+json

Schema

All API access is over HTTPS, and accessed from the https://api.tookapic.com. All data is sent and received as JSON.

$ curl -i https://api.tookapic.com/users/idered

HTTP/1.0 200 OK
Host: api.tookapic.com
Date: Thu, 31 Mar 2016 08:03:35 GMT
Connection: close
Content-type: application/json
Cache-Control: no-cache
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1459411715

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -i "https://api.tookapic.com/tags/friday?sort=recent"

In this example, the 'friday' value is provided for the :name parameter in the path while :sort is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

VerbDescription
GETUsed for retrieving resources.
POSTUsed for creating resources.
PUTUsed for updating resources, or performing custom actions.
DELETEUsed for deleting resources.

Authentication

There are two ways to authenticate through tookapic API.

OAuth2 Token (sent in a header)
$ curl -H "Authorization: Bearer OAUTH_TOKEN" https://api.tookapic.com/users/:username
OAuth2 Token (sent as a parameter)
$ curl "https://api.tookapic.com/users/:username?access_token=OAUTH_TOKEN"

Pagination

Requests that return multiple items will be paginated to 10 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 50 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

$ curl "https://api.tookapic.com/users?page=2&per_page=40"

Note that omitting the ?page parameter will return the first page.

Rate Limiting

For requests using OAuth, you can make up to 1000 requests per hour. For unauthenticated requests, the rate limit allows you to make up to 50 requests per 15 minutes.

You can check the returned HTTP headers of any API request to see your current per minute rate limit status:

$ curl -i https://api.tookapic.com/users

HTTP/1.1 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 1459411715

The headers tell you everything you need to know about your current rate limit status:

VerbDescription
X-RateLimit-LimitThe maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-RemainingThe number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

new Date(1459411715 * 1000)
// => Thu Mar 31 2016 10:08:35 GMT+0200 (Central European Daylight Time)

Once you go over the rate limit you will receive an error response:

HTTP/1.0 403 Forbidden
Date: Thu, 31 Mar 2016 09:04:44 GMT
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1459415140

{"message":"403 Forbidden","status_code":403}

JSON-P Callbacks

You can send a ?callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed tookapic content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

You can write a JavaScript handler to process the callback. Here's a minimal example you can try out:

<html>
<head>
    <script type="text/javascript">
        function foo(response) {
            var meta = response.meta;
            var data = response.data;
            console.log(meta);
            console.log(data);
        }

        var script = document.createElement('script');
        script.src = 'https://api.tookapic.com/users?callback=foo';

        document.getElementsByTagName('head')[0].appendChild(script);
    </script>
</head>
</body>
</html>

Pawel from Tookapic

Hi, I’m happy to help you with any tookapic subject, however, before you send me a message, please look at Help section where you can find answers for most questions.

We’ll reply shortly!

Please note that answers for most questions about tookapic can be found in the Help section.