Diigo API

Overview

The Diigo API allows you to build apps that interact with the Diigo service. You can use the API to fetch or post bookmarks for a user.

Different API versions are namespaced by a URL prefix. The current version is v2. All API method URLs begin with https://secure.diigo.com/api/v2/

The Diigo API is entirely HTTP based and conform to HTTP standards and conventions, making it easy to use with standard technologies.

The API is still under development and is subject to change. If you have any questions or suggestions, please contact service@diigo.com.

Authentication

Diigo API uses HTTP Basic authentication - a standard authentication method that includes base64 encoded username and password in the Authorization request header. Developers must NOT use the credentials provided by users for any other purposes. Other authentication options such as OAuth may be supported in future.

RESTful API style

The Diigo API attempts to embrace the RESTful design principles.

Each api method URL corresponds to a resource. The HTTP method (aka. verb) is used to specify the operation. A GET request is used to retreive data. A POST request may add, update or destroy data. The DELETE method is also accepted for methods that destroy data. API methods usually require particular HTTP methods. Such requirements are documented for each method.

Request Parameters and Encoding

The Diigo API only accepts and returns text encoded in UTF-8.

The Diigo API uses standard HTTP query string to pass parameters. Parameters are required to be properly URL encoded.

Responses

The Diigo API attempts to returns meaningful HTTP status codes for each request. Possible codes are

200 OK: Success!
400 Bad Request: Some request parameters are invalid or the API rate limit is exceeded.
401 Not Authorized: Authentication credentials are missing or invalid.
403 Forbidden: The request has been refused because of the lack of proper permission.
404 Not Found: Either you're requesting an invalid URI or the resource in question doesn't exist (e.g. no such user).
500 Internal Server Error: Something is broken.
502 Bad Gateway: Diigo is down or being upgraded.
503 Service Unavailable: The Diigo servers are too busy to server your request. Please try again later.

The response body contains data in the JSON format - a light weight serialization format for structured data.

API Methods

Retrieve bookmarks

Returns a list of bookmarks satisfying various criteria

URL: https://secure.diigo.com/api/v2/bookmarks

Request method: GET

Parameters

user ;required, string, the username of whose bookmarks to fetch
start ;optional, number, the start offset of the bookmarks to fetch starting from 0, defaults to 0
count ;optional, number, the number of bookmarks to fetch, defaults to 10, max:100
sort ;optional, number 0-3, determines the order of bookmarks to fetch, 0: created_at, 1: updated_at, 2: popularity, 3: hot, defaults to 0
tags ;optional, string, only bookmarks with specified tags will be returned. multiple tags are separated by comma
filter ;optional, string, public: only returns public bookmarks; all: returns all bookmarks including private ones, defaults to public
list ;optional, string, the list name of a bookmark list, when specified, user must be also specified

Example request:

https://secure.diigo.com/api/v2/bookmarks?user=joel&count=10

Response

An array of bookmarks.

Example Response (JSON)

[
  {
    "title":"Diigo API Help",
    "url":"http:\/\/www.diigo.com\/help\/api.html",
    "user":"foo",
    "desc":"",
    "tags":"test,diigo,help",
    "shared":"yes",
    "created_at":"2008/04/30 06:28:54 +0800",
    "updated_at":"2008/04/30 06:28:54 +0800",
    "comments":[],
    "annotations":[]
  },
  {
    "title":"Google Search",
    "url":"http:\/\/www.google.com",
    "user":"bar",
    "desc":"",
    "tags":"test,search",
    "shared":"yes",
    "created_at":"2008/04/30 06:28:54 +0800",
    "updated_at":"2008/04/30 06:28:54 +0800",
    "comments":[],
    "annotations":[]
  }
]

Save bookmark

Saves a bookmark for the authenticated user

URL: https://secure.diigo.com/api/v2/bookmarks

Request method: POST

Parameters

title ;required, string 1-250, the title of the bookmark
url ;required, string 1-250, the url of the bookmark
shared ;optional, string, the value can be yes/no, yes means the bookmark is public, no means the bookmark is private, defaults to no
tags ;optional, string, 1-250, tags separated by comma
desc ;optional, string 1-250, the description for the bookmark
readLater ;optional, string, value can be yes/no, specifies whether the bookmark is "unread", defaults to no

Example request

POST https://secure.diigo.com/api/v2/bookmarks

?url=http%3A%2F%2Fwww.diigo.com&title=Diigo+-+Web+Highlighter+and+Sticky+Notes&tags=diigo,bookmark,highlight
&shared=yes

Reponse

Example Response

{ "message" : "added 1 bookmark(s)" }

Diigo Tools