The gubb API

Introduction / Open Letter to Developers

The gubb API exists to help developers create non-commercial applications, browser plug-ins and other software that interacts with data inside of gubb. If you would like to create a commercial application with the gubb API, please contact gubb at support[at]gubb.net (we are open to possibilities).

Very Exciting Point: The gubb API offers the ability to filter/query items across lists (abilities not exposed in the gubb web application). You can easily ask questions like: what's high priority? what is due soon? what was added recently? Analytics! These special features offer you considerable creative freedom and power!

The community will have broader and more creative ideas than us, but here's a jumpstart on the intersection between what is possible with the new API and what gubb users have expressed interest in:

Google, Dashboard and Vista widgets that display your high priority items, upcoming due dates, etc.
Amazon Wishlist two-way sync'ing
Parse your grocery list and automatically order your groceries (FreshDirect, Peapod)
The obvious: email, calendar and Firefox integration

We are committed to supporting development efforts (both closed- and open-source) that make your lists more available and smarter. Awards, recognition and promotion, cross-platform testing, hosting, customer service for users ... we're here to provide the support network that developers want. We're here for you (and we know we need you).

A community support group is now available at groups.google.com/group/gubb-developers where gubb developers read and respond to information ASAP.

And, the gubb API is a work-in-progress. We are 100% open to quickly adding support for other formats (OPML? microformats?) and extending the API with new convenience methods. Let's talk using the support group, and also feel free to contact us at any time via support[at]gubb.net

Quick Facts:

the gubb API is REST-based; you use the API through HTTP GET and POST requests
the API methods are user-centric: all API calls are "on behalf of" whatever user you authenticate as
the API's interface is detailed below, method by method
the API is accessible via both HTTPS (SSL) and HTTP, and gubb recommends using HTTPS if at all possible
the API receives GET and POST requests with normal HTTP parameters, and
the API returns XML, JSON, HTML and Text responses (dependent upon the format requested)
in the event of errors, the API returns an HTTP status code (404 or 400) and a descriptive text response

API Reference

Authentication & Security

The Basics

List Comments
Item Comments

Authentication & Security Back to Top

There are two equivalent ways to authenticate the user: User API Keys and HTTP Basic Authentication (both preferably over HTTPS). If asked for a preference as to how people should authenticate, we'd request that you use the User API Key method because it allows for easy repeated use without requiring that you store the user's gubb username and password. In any case, we'll repeat again that HTTPS should be used wherever possible.

User API KeyBack to Top

User API Keys are 30 character alphanumeric strings that uniquely identify and authenticate a user. Of course, User API Keys are meant to be kept secret since knowing a user's API Key gives you access to all the user's list information.

To get a User API Key, users should go to https://gubb.net/home/api, where they will see a standard gubb dialog with instructions for getting a User API Key. The process is as simple as clicking a button and copying/pasting the resulting alphanumeric string.

To authenticate a user using a User API Key, include a POST parameter named "api_key" with the 30 character User API Key as the parameter's value in all API HTTP requests. We indicate POST parameter usage only because URLs (and soemtimes all GET parameters) are often logged and therefore slightly less secure.

HTTP Basic AuthenticationBack to Top

By way of the user's gubb username/password, you may authenticate a user with HTTP Basic Authentication. Most HTTP libraries allow for convenient HTTP Basic Authentication -- please contact gubb at support[at]gubb.net if you have any questions regarding how-tos for your language. In the future, we hope to produce "gubb API libraries" implemented in a number of languages.

Basics of gubb's API Back to Top

URL StructuresBack to Top

The general URL structures are:

/api/[object-class]/[method-name] and

/api/[object-class]/[method-name].[response-format]

where,

[object-class] is one of: list, item, list_comment and item_comment
[method-name] is the method name, typically one of: get, create, update, delete
[response-format] is the desired response format, typically one of: xml, json, html, txt (note that dot (.) before the format!)

Response FormatsBack to Top

The [response-format] that you provide dictates the format of the response. Possible response formats are xml, json, html and txt. See the reference for particular methods to see the formats that they support. In cases where the only return value is only a success/failure message, you will receive an HTTP status code as well as a descriptive text response. See individual method calls for supported response formats.

xml

If you want to get the list with the unique id of 1 in XML form, your request URL is:
https://gubb.net/api/list/get.xml?id=1

The XML returned is very vanilla, without any attributes at all and relying solely on simple and dependable PCDATA (parse/massage as you wish) described in the methods reference below.

json

If you want to get the list with the unique id of 1 in JSON form, your request URL is:
https://gubb.net/api/list/get.json?id=1

We believe our JSON to be compliant with the JSON RFC for data transfer (and object notation), including:

double quotes surrounding all names and string values (in terms of name/value pairs)
integers represented as integers (no surrounding double quotes)
nil/null values represented as "null" (without double quotes)
dates are represented as string values, in standardized form (see Dates as Return Fields)
object ({}) and array ([]) notation where appropriate

html

If you want to get the list with the unique id of 1 in HTML form, your request URL is:
https://gubb.net/api/list/get.html?id=1

HTML is returned in "shards," without full HTML document structure. We did this to accommodate folks who wanted to easily include gubb lists in other web pages. CSS styling is a good option as the resulting HTML shards are simple and reliable in structure.

txt

If you want to get the list with the unique id of 1 in plain text form, your request URL is:
https://gubb.net/api/list/get.txt?id=1

For naked basic lists, try the text responses.

Error ResponsesBack to Top

In the event of an error, you will receive an HTTP status code 404 if the object was not found and an HTTP status code 400 in all other error cases. In addition to the status code, you will receive a descriptive text message. We are in the process of "tailing" error messages with an error code (e.g. "Invalid due date format (203)") to ease error processing, but we have not completed that functionality yet.

Dates as Return Fields Back to Top

All dates returned are in ISO 8601 format (e.g. 20071230T14:00Z) and are in the UTC time zone.

How To Use filter_* Parameters Back to Top

Where the filter_* parameters are an option, you are able to "filter" the items on the relevant list(s) for certain qualities (such as priority). This feature gives you power way beyond what is currently exposed in the gubb web application and should enable a lot of creativity!

The available filter_* parameters and associated allowed values are:

filter_status: one of [all, archived, incomplete, active_completed]. The "all" value is a special one, it overrides all other filter_* parameters and ensures the the method call will return all items for the list(s).
filter_date_created: an integer followed by one of [d,h,m] where "d" implies "days ago," "h" implies "hours ago," and "m" implies "minutes ago."
Examples:
- filter_date_created=20h will filter for items created less than 20 hours ago
filter_date_completed: an integer followed by one of [d,h,m] where "d" implies "days ago," "h" implies "hours ago," and "m" implies "minutes ago."
Examples:
- filter_date_completed=20h filters for items completed less than 20 hours ago
filter_date_modified: an integer followed by one of [d,h,m] where "d" implies "days ago," "h" implies "hours ago," and "m" implies "minutes ago."
Examples:
- filter_date_modified=20h filters for items modified less than 20 hours ago
filter_date_due: an integer followed by a "d" OR the value "null."
Examples:
- filter_date_due=14d filters for items that are due less than 14 days from now
- filter_date_due=null filters for items that do not have due dates
filter_date_last_commented_on: an integer followed by one of [d,h,m] where "d" implies "days ago," "h" implies "hours ago," and "m" implies "minutes ago."
Examples:
- filter_date_last_commented_on=20h filters for items commented on less than 20 hours ago
filter_priority: one of [null, 1, 1+, 2, 2+, 3, 3+].
Examples:
- filter_priority=null filters for items without any priority
- filter_priority=2 filters for items with a priority of exactly 2 (stars)
- filter_priority=1+ filters for items with a priority of 1 or more (stars) (so, it matches priorities 1, 2 and 3)

Important Notes:

Filters are "AND-ed" together. For example, if you supply GET parameters of "filter_status=incomplete&filter_date_completed=1d" then you end up with no items returned. This is because there are no items that are incomplete AND completed less than a day ago.
One exception to the rule above: if you provide the filter_status parameter with the value "all" then you will override all other filters and all items will be returned.
We do not return errors if you supply invalid filter parameters or values (invalid filter parameter/value pairs will just have no effect).

Examples:

These examples use GET URLs to keep the examples compact, but you could (and probably should) use POST parameters instead.

/api/list/get/1.json?filter_priority=3&filter_status=incomplete
returns all incomplete 3-star priority items for the list with id=1 (in JSON format)
/api/list/get_all.json?filter_date_due=3d&filter_status=incomplete
returns an array of all your lists and each list includes only incomplete items that are due less than 3 days from now (in JSON format)

API Methods Reference

Getting a Single List (with or without items)Back to Top

Method URL: /api/list/get

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list.
filter_* parameters	[Default: no items returned] (See How To Use filter_* Parameters)

Response Fields	Notes
id	Unique integer id for the list
name	Name of the list
background	The background color for the list, given in Hex form (e.g. #FFFFFF)
description	The description, if any, for the list
owner_username	The gubb username of the list's owner. See "Email Name" below for the Owner Username's use in determining the list's unique email address.
email_name	The email name of the list, used in determining the list's unique email address. Email addresses look like: [owner_username]-[list_email_name]@gubb.net.
auto_archive_completed	0 or 1, boolean indicating whether or not list items are automatically archived when completed
date_last_commented_on	The date of the last list comment for the list, empty if there are no list comments for the list (see Dates as Return Fields)

Getting Some of a User's Lists Back to Top

Method URL: /api/list/get_some

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
list_ids	[Required] Comma separated (without spaces) list of list ids. For example, as a GET parameter: "list_ids=1,2,3" where you'd like to get the lists with ids 1, 2 and 3.
filter_* parameters	[Default: no items returned] (See How To Use filter_* Parameters)

Response Fields	Notes
lists	A parent element for zero or more list objects. (See the response fields for Getting a Single List for information on child elements)

Getting All of a User's Lists (with or without items)Back to Top

Method URL: /api/list/get_all

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
filter_* parameters	[Default: no items returned] (See How To Use filter_* Parameters)

Response Fields	Notes
lists	A parent element for zero or more list objects. (See the response fields for Getting a Single List for information on child elements)

Creating a New List Back to Top

Method URL: /api/list/create

Supported Formats: xml, json, html, txt (only xml and json include all response fields), in the event of an error this method will return an HTTP status code 400 and a descriptive text message

Request Parameters	Accepted Values
name	[Required] Name for the new list. Must be unique amongst the user's lists and a maximum of 50 characters long.
background	[Default: #FFFFFF] A Hex color value for this list's background (including the leading pound character(#))
description	[Default: none]
list_type	[Default: 1] Must be either 1 or 2, where 1 indicates a Task List and 2 indicates a Bulleted List
auto_archive_completed	[Default: 0] Must be either 0 or 1, where 0 indicates that items are not auto-archived (when completed) and 1 indicates that items are auto-archived when completed

Response Fields	Notes
list	Same as the response fields for Getting a Single List

Updating an Existing List Back to Top

Method URL: /api/list/update

Supported Formats: xml, json, html, txt (only xml and json include all response fields), in the event of an error this method will return an HTTP status code 404-not-found or 400-error and a descriptive text message

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list
name	[If not present: no change] Name for the new list. Must be unique amongst the user's lists and a maximum of 50 characters long.
background	[If not present: no change] A Hex color value for this list's background (including the leading pound character(#))
description	[If not present: no change]
list_type	[If not present: no change] Must be either 1 or 2, where 1 indicates a Task List and 2 indicates a Bulleted List
auto_archive_completed	[If not present: no change] Must be either 0 or 1, where 0 indicates that items are not auto-archived (when completed) and 1 indicates that items are auto-archived when completed

Response Fields	Notes
list	Same as the response fields for Getting a Single List

Deleting a List Back to Top

Method URL: /api/list/delete

Supported Formats: None - Response is an HTTP status code (200-success, 400-error or 404-not-found) and descriptive text message

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list

Getting a Single Item Back to Top

Method URL: /api/item/get

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item.

Response Fields	Notes
id	Unique integer id for the item
list_id	Unique integer id for the item's list
note
details
date_due	(see Dates as Return Fields)
priority	Empty, 1, 2 or 3 where the numbers indicate the number of stars gubb uses to represent priority
date_created	(see Dates as Return Fields)
date_completed	Empty if the item is not complete (see Dates as Return Fields)
date_modified	(see Dates as Return Fields)
date_last_commented_on	Empty if the item has no item comments (see Dates as Return Fields)
archived	0 or 1, where 0 indicates not archived and 1 indicates archived
editor_user_id	User id for the most recent editor of the item
completed_by_id	User id for the user who marked the item as complete (empty if not complete)
assignee_user_id	User id for the user to whom this item is assigned, empty if no assigment

Creating a New Item Back to Top

Method URL: /api/item/create

Supported Formats: xml, json, html, txt (only xml and json include all response fields), in the event of an error this method will return an HTTP status code 400-error and a descriptive text message

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item's list
note	[Required] 250 characters maximum
details	1000 characters maximum
date_due	Same date inputs supported as gubb web application (including natural language date support)
priority	Empty, 1, 2 or 3 where the numbers indicate the number of stars that gubb uses to represent priority
assignee_user_id	User id for the user to whom this item is assigned, empty if no assigment

Response Fields	Notes
item	Same as the response fields for Getting a Single Item

Updating an Existing Item Back to Top

Method URL: /api/item/update

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item.
note	[If not present: no change]
details	[If not present: no change] Include the parameter but leave empty to null/clear the details.
date_due	[If not present: no change] Include the parameter but leave empty to null/clear the details.
priority	[If not present: no change] Include the parameter but leave empty to null/clear the details. Empty, 1, 2 or 3 where the numbers indicate the number of stars that gubb uses to represent priority
assignee_user_id	[If not present: no change] Include the parameter but leave empty to null/clear the details. User id for the user to whom this item is assigned, empty if no assigment
move_to_list_id	[If not present: no change] If present, should indicate the unique integer id for the list that you are moving the item to.

Response Fields	Notes
item	Same as the response fields for Getting a Single Item

Marking an Item as Completed Back to Top

Method URL: /api/item/mark_completed

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item.

Response Fields	Notes
item	Same as the response fields for Getting a Single Item

Marking an Item as Incomplete Back to Top

Method URL: /api/item/mark_incomplete

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item.

Response Fields	Notes
item	Same as the response fields for Getting a Single Item

Deleting an Item Back to Top

Method URL: /api/item/delete

Supported Formats: None - Response is an HTTP status code (200-success, 400-error or 404-not-found) and descriptive text message

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item

Getting a Single List Comment Back to Top

Method URL: /api/list_comment/get

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list comment

Response Fields	Notes
id	Unique integer id for the list comment
list_id	Unique integer id for the list comment's list
user_id	gubb user id for the user who created the list comment
date_created	(see Dates as Return Fields)
note

Getting All of a List's Comments Back to Top

Method URL: /api/list_comment/get_all

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list comment's list

Response Fields	Notes
list_comments	A parent element for zero or more list comment objects. (See the response fields for Getting a Single List Comment for information on child elements)

Creating a New List Comment Back to Top

Method URL: /api/list_comment/create

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list comment's list
note	[Required]

Response Fields	Notes
list_comment	Same as the response fields for Getting a Single List Comment

Deleting a List Comment Back to Top

Method URL: /api/list/delete

Supported Formats: None - Response is an HTTP status code (200-success, 400-error or 404-not-found) and descriptive text message

Request Parameters	Accepted Values
id	[Required] Unique integer id for the list comment

Getting a Single Item Comment Back to Top

Method URL: /api/item_comment/get

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item comment

Response Fields	Notes
id	Unique integer id for the item comment
item_id	Unique integer id for the item comment's item
user_id	gubb user id for the user who created the item comment
date_created	(see Dates as Return Fields)
note

Getting All of an Item's Comments Back to Top

Method URL: /api/item_comment/get_all

Supported Formats: xml, json, html, txt (only xml and json include all response fields)

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item comment's item

Response Fields	Notes
item_comments	A parent element for zero or more item comment objects. (See the response fields for Getting a Single Item Comment for information on child elements)

Creating a New Item Comment Back to Top

Method URL: /api/item_comment/create

Request Parameters	Accepted Values
id	[Required] Unique integer id for the item comment's item
note	[Required]

Response Fields	Notes
item_comment	Same as the response fields for Getting a Single Item Comment

Deleting a Item Comment Back to Top

Method URL: /api/item/delete

Supported Formats: None - Response is an HTTP status code (200-success, 400-error or 404-not-found) and descriptive text message

Request Parameters	Accepted Values
id	Unique integer id for the item comment