API v1
Note: This API is in a beta state. Breaking changes may occur.
This documentation has been heavily inspired by the excellent Github API.
Terms of use
The Desktoppr API can be used for any non-commercial applications. If you wish to use the API for a commercial application, please contact us first.
Our terms are very brief, if you have good intentions then you're more than likely already following them. Here are the details:
- The original copyright holders own all rights to their content and it is your responsibility to make sure your use of the API does not contravene those rights.
- You must remove from your application within 24 hours any wallpaper or personal information that the owner asks you to remove.
- Do not use the name Desktoppr in your application, URL or branding without prior permission.
- Do not use the Desktoppr API for any application that replicates or attempts to replace the essential user experience of desktoppr.co
- If your application derives revenue from its use of the Desktoppr API, it is considered a commercial application. Desktoppr reserves the right to evaluate and monitor commercial applications to ensure that they do not harm Desktoppr's servers or business interests.
- Do not abuse the API or use it excessively. If you're unsure whether your planned use is excessive, ask us.
- Desktoppr may terminate your license to the Desktoppr API under these terms at any time for any reason.
- Desktoppr reserves the right to update and change these terms from time to time without notice.
Schema
All API access is over HTTPS, and accessed from the api.desktoppr.co
domain. All data is sent as JSON.
$ curl -i https://api.desktoppr.co
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 02 May 2012 12:27:58 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
X-Ua-Compatible: IE=Edge,chrome=1
Etag: "b378f703c80e912313457fdf0f60ca76"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 9065d09226cbf357b017cf0dcbce7704
X-Runtime: 0.007885
X-Rack-Cache: miss
Content-Length: 7
X-Varnish: 1268559407
Age: 0
Via: 1.1 varnish
{ "response": "Hello World" }
The Desktoppr API also has JSONP support. Simply add a callback
paramater to any API GET request (excluding the whoami endpoint), and it will wrap the response up in a function:
$ curl https://api.desktoppr.co?callback=hello
hello({
response: "Hello World"
})
Authentication
At present, there are only two ways to authenticate against the Desktoppr API:
Basic Authentication:
$ curl -u "username:PASSWORD" https://api.desktoppr.co/1/user/whoami
{
"response": {
"username": "keithpitt",
"name": "Keith Pitt",
"avatar_url": "https://...",
"wallpapers_count": 80,
"uploaded_count": 200,
"followers_count": 39,
"following_count": 76,
"api_token":"xR4YxRm3yMwo8As4zE6V",
"created_at": "2012-04-10T11:29:25Z"
}
}
Once you have authenticated with username and password, you can use the returned API token for further authenticated requests like so:
Token Authentication:
$ curl https://api.desktoppr.co/1/user/whoami?auth_token=API_TOKEN
{
"response": {
"username": "keithpitt",
"name": "Keith Pitt",
"avatar_url": "https://...",
"wallpapers_count": 80,
"uploaded_count": 200,
"followers_count": 39,
"following_count": 76,
"created_at": "2012-04-10T11:29:25Z"
}
}
Note: You can also find your API token on the user settings page.
Users
To get user information based on a users username
$ curl https://api.desktoppr.co/1/users/keithpitt
{
"response": {
"username": "keithpitt",
"name": "Keith Pitt",
"avatar_url": "https://...",
"wallpapers_count": 80,
"uploaded_count": 200,
"followers_count": 39,
"following_count": 76,
"created_at": "2012-04-10T11:29:25Z"
}
}
To get a paginated list of wallpapers that a user has in their collection
At the moment, we have hard coded the per page setting to be 10. This may change in the future.
$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers
{
"response": [ {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
} ],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": 2,
"per_page": 10,
"pages": 1,
"count": 1
}
}
By default only wallpapers marked as safe are returned. This can be changed by passing a safe_filter
parameter. The parameter can have the following values:
safe
: This is the default, only returns safe wallpapers.include_pending
: Returns safe as well as pending (not yet rated) wallpapers.all
: Returns all wallpapers, including not safe for work wallpapers.
$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers?safe_filter=all
{
"response": [ {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
} ],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": 2,
"per_page": 10,
"pages": 1,
"count": 1
}
}
To get a random wallpaper that a user has in their collection
$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers/random
{
"response": {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
}
}
To get a paginated list of wallpapers that a user has liked
$ curl https://api.desktoppr.co/1/users/keithpitt/likes
{
"response": [ {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
} ],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": 2,
"per_page": 10,
"pages": 1,
"count": 1
}
}
Followers
To get a paginated list of users that a user has followed, or are following, you can use the following endpoints:
$ curl https://api.desktoppr.co/1/users/keithpitt/followers
{
"response": [ { ... } ],
"count": "...",
"pagination": "..."
}
$ curl https://api.desktoppr.co/1/users/keithpitt/following
{
"response": [ { ... } ],
"count": "...",
"pagination": "..."
}
You can follow a user as follows:
$ curl -u "username:PASSWORD" -X POST \
http://api.desktoppr.co/1/users/keithpitt/follow
{
"response": {
"ok": true
}
}
And to unfollow:
$ curl -u "username:PASSWORD" -X DELETE \
http://api.desktoppr.co/1/users/keithpitt/follow
{
"response": {
"ok": true
}
}
Wallpapers
To get all wallpapers in the database that have been marked as safe:
$ curl https://api.desktoppr.co/1/wallpapers
{
"response": [ {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
} ],
"count": 13435,
"pagination": {
"current": 1,
"previous": null,
"next": 2,
"per_page": 10,
"pages": 341,
"count": 1
}
}
You can append a page parameter to cycle through different pages
$ curl https://api.desktoppr.co/1/wallpapers?page=2
{
"response": [ {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
} ],
"count": 20,
"pagination": {
"current": 2,
"previous": 1,
"next": 3,
"per_page": 20,
"pages": 3558,
"count": 71142
}
}
As with a users wallpaper, you can grab a random SFW wallpaper from our entire database using:
$ curl https://api.desktoppr.co/1/wallpapers/random
{
"response": {
"id": 380,
"bytes": 990121,
"created_at": "2012-04-11T10:33:27Z",
"image":{
"url": "http://...",
"thumb": {
"url":"http://..."
},
"preview": {
"url":"http://..."
},
},
"height":1080,
"width":1920,
"uploader":"mariovisic",
"user_count":3,
"palette":[
"C4C9CA",
"7D95A1",
"282827",
"32515A",
"636139"
]
}
}
Liking
Liking of wallpapers can be performed via the API. You'll need to be authenticated to like a paticular wallpaper as the current user will be the one liking the wallpaper.
$ curl -u "username:PASSWORD" -X POST http://api.desktoppr.co/1/user/wallpapers/100/like
{
"response": {
"ok": true
}
}
To unlike a previously liked wallpaper
$ curl -u "username:PASSWORD" -X DELETE http://api.desktoppr.co/1/user/wallpapers/100/like
{
"response": {
"ok": true
}
}
You can determine if the user has liked a paticular wallpaper, by adding a wallpaper_id
query to the call.
$ curl https://api.desktoppr.co/1/users/keithpitt/likes?wallpaper_id=184381
{
"response": [ { ... } ],
"count": "1",
"pagination": "..."
}
It will either return a list with 1 wallpaper if they have liked it already, or an empty list if they haven't.
Syncing
Just like liking, syncing can also be performed via the API.
$ curl -u "username:PASSWORD" -X POST \
http://api.desktoppr.co/1/user/wallpapers/100/selection
{
"response": {
"ok": true
}
}
To unsync a previously synced wallpaper
$ curl -u "username:PASSWORD" -X DELETE \
http://api.desktoppr.co/1/user/wallpapers/100/selection
{
"response": {
"ok": true
}
}
You can determine if the user has synced a paticular wallpaper, by adding a wallpaper_id
query to the call.
$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers?wallpaper_id=256167
{
"response": [ { ... } ],
"count": "1",
"pagination": "..."
}
It will either return a list with 1 wallpaper if they have synced it already, or an empty list if they haven't.
Flagging
Users can flag a wallpaper to indicate it is safe for work, not safe for work, or not suitable for the website and should be deleted. Flagging requires you to be logged in.
Flagging a wallpaper as safe for work:
$ curl l -u "username:PASSWORD" -X POST \
https://api.desktoppr.co/1/wallpapers/30000/flag_safe
{
"response": [ { ... } ],
"count": "...",
"pagination": "..."
}
Flagging a wallpaper as not safe for work:
$ curl l -u "username:PASSWORD" -X POST \
https://api.desktoppr.co/1/wallpapers/30000/flag_not_safe
{
"response": [ { ... } ],
"count": "...",
"pagination": "..."
}
Flagging a wallpaper for deletion as it is not appropriate for the site:
$ curl l -u "username:PASSWORD" -X POST \
https://api.desktoppr.co/1/wallpapers/30000/flag_deletion
{
"response": [ { ... } ],
"count": "...",
"pagination": "..."
}
Applications using the API
Some rather nice people have built application or tools that use the desktoppr API. Here they are
-
Tate's Chrome Extension for Desktoppr
This extension displays a different wallpaper each time you open a new tab in Google Chrome.
Download Source -
Muzei Desktoppr Extension
An open source extension for the Muzei Live Wallpaper on Android. Periodically sets a random Desktoppr image as the device wallpaper
Download Source