Developer

Overview

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

Schema

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

$ curl -i https://api.dribbble.com/v1/users/simplebits

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

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.dribbble.com/v1/users/simplebits/followers?page=2"

In this example, the “simplebits” value is provided for the user parameter in the path while 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.

Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for updating resources, or performing custom actions.
DELETE Used for deleting resources.

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/v1/user

OAuth2 Token (sent as a parameter)

$ curl "https://api.dribbble.com/v1/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/v1/user/followers?page=2&per_page=100"

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

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/v1/user/followers?page=1&per_page=100>; rel="prev",
  <https://api.dribbble.com/v1/user/followers?page=3&per_page=100>; rel="next"

The possible rel values are:

Name Description
next Shows the URL of the immediate next page of results.
prev Shows the URL of the immediate previous page of results.

Rate Limiting

For requests using OAuth, you can make up to 60 requests per minute and 1,440 requests per day per authenticated user. For unauthenticated requests using your application’s client access token, you can make up to 60 requests per minute and 10,000 requests per day.

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/v1/users/simplebits

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:

Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per minute.
X-RateLimit-Remaining The 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(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/v1/users/simplebits
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/v1/users/simplebits -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/v1/users/simplebits -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/v1/users/simplebits -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/v1/users/simplebits -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

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 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.

$ curl "https://api.dribbble.com?callback=bar"

bar({
  "meta" : {
    "status" : 200,
    "X-RateLimit-Limit" : 60,
    "X-RateLimit-Remaining" : 59,
    "X-RateLimit-Reset" : 1392321600,
    "Link" : [
      ["https://api.dribbble.com?page=2", { "rel" : "next" }]
    ]
  },
  "data" : {
    // ...
  }
})

You can write a JavaScript handler to process the callback like this:

function bar(response) {
  var meta = response.meta
  var data = response.data

  console.log(meta)
  console.log(data)
}

All of the headers are the same String value as the HTTP Headers with one notable exception: Link. Link headers are pre-parsed for you and come through as an array of [url, options] tuples.

A link that looks like this:

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

… will look like this in the callback output:

{
  "Link" : [
    [
      "url1",
      {
        "rel" : "next"
      }
    ],
    [
      "url2",
      {
        "rel" : "foo",
        "bar" : "baz"
      }
    ]
  ]
}