Overview for the v2 API

Please note that you must register your application and authenticate with OAuth when making requests. Before doing so, be sure to read our Terms & Guidelines to learn how the API may be used.

• Schema
• Timestamps
• Parameters
• Client Errors
• HTTP Verbs
• Authentication
• Pagination
• Rate Limiting
• Conditional requests
• Cross Origin Resource Sharing

Schema

All API access is over HTTPS, and accessed from the api.dribbble.com/v2/ endpoint. All data is sent and received as JSON.

$ curl -i https://api.dribbble.com/v2/user

HTTP/1.1 200 OK
Date: Thu, 13 Feb 2014 19:30:30 GMT
ETag: "def2bc69c674e5b48cd281aa12c2c8e9"
Server: nginx
Status: 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

Timestamps

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.dribbble.com/v2/user/shots?page=2"

In this example, page is passed in the query string.

For POST, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of “application/x-www-form-urlencoded”.

Client Errors

There are two possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON.

Status: 400 Bad Request
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

{
  "message" : "Problem parsing JSON."
}

2. Sending invalid fields.

Status: 422 Unprocessable Entity
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

{
  "message" : "Validation failed.",
  "errors" : [
    {
      "attribute" : "body",
      "message" : "can't be blank"
    }
  ]
}

HTTP Verbs

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

Authentication

There are two ways to authenticate through Dribbble API.

OAuth2 Token (sent in a header)

$ curl -H "Authorization: Bearer OAUTH_TOKEN" https://api.dribbble.com/v2/user

OAuth2 Token (sent as a parameter)

$ curl "https://api.dribbble.com/v2/user?access_token=OAUTH_TOKEN"

Pagination

Requests that return multiple items will be paginated to 30 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 100 with the per_page parameter. Note that for technical reasons not all endpoints respect the per_page parameter.

$ curl "https://api.dribbble.com/v2/user/shots?page=2&per_page=100"

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

Link Header

The pagination info is included in the Link header. It is possible for some resources in the future to not be paginated based on page number, so it is important to follow these Link header values instead of constructing your own URLs. For example, when requesting the second page the following headers may be provided:

Link: <https://api.dribbble.com/v2/user/shots?page=1&per_page=100>; rel="prev",
  <https://api.dribbble.com/v2/user/shots?page=3&per_page=100>; rel="next"

The possible rel values are:

Rate Limiting

For requests using OAuth, you can make up to 60 requests per minute and 1,440 requests per day per authenticated user.

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

$ curl -i https://api.dribbble.com/v2/user/shots

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

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

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(1392321600 * 1000)
// => Thu Feb 13 2014 14:00:00 GMT-0600 (CST)

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

HTTP/1.1 429 Too Many Requests
Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1392321600

{ "message" : "API rate limit exceeded." }

Staying within the rate limit

If you are exceeding your rate limit, you can likely fix the issue by caching API responses.

Conditional requests

Most responses return an ETag header. Many responses also return a Last-Modified header. You can use the values of these headers to make subsequent requests to those resources using the If-None-Match and If-Modified-Since headers, respectively. If the resource has not changed, the server will return a 304 Not Modified.

$ curl -i https://api.dribbble.com/v2/user
HTTP/1.1 200 OK
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

$ curl -i https://api.dribbble.com/v2/user -H 'If-None-Match: "e612e16d3c4d113573edb015d8eac1d5"'
HTTP/1.1 304 Not Modified
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

$ curl -i https://api.dribbble.com/v2/user -H "If-Modified-Since: Sat, 22 Feb 2014 17:10:33 GMT"
HTTP/1.1 304 Not Modified
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. You can read the CORS W3C working draft, or this intro from the HTML 5 Security Guide.

Here’s a sample request sent from a browser hitting http://example.com:

$ curl -i https://api.dribbble.com/v2/user -H "Origin: http://example.com"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Expose-Headers: ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Allow-Credentials: true

This is what the CORS preflight request looks like:

$ curl -i https://api.dribbble.com/v2/user -X OPTIONS -H "Origin: http://example.com" -H "Access-Control-Request-Method: GET"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: OPTIONS, GET
Access-Control-Expose-Headers: ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true