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