Developer's API Documentation : Upgrading to API v3

What's New

• Authentication is done with OAuth2 now. This is much more secure and you no longer need to store user's passwords. If a user changes their password your app doesn't need to know. You can now request limited access to the API to give customers more trust.
• All numbers are returned as numbers instead of string versions of numbers.
• All errors now contain unique ids across the entire API and are well documented.
• Relevant errors will contain a reference to the item that caused the error so you can more easily link the error to the item in your application.
• You can now edit the "private" flag on contexts and goals.
• You can now edit a goal's note.
• Task metadata can now contain up to 1024 bytes per task of custom data for your app to use for whatever purpose.
• The "repeat" attribute on a task is now represented as a standard iCal RRule.
• You can access and edit outlines and lists.
• You can access a task's attachments (lists, notes, outlines, and filenames).
• Some method and field names have been renamed for consistency. For example, "notebook" has been renamed to "notes". Please check the documentation for details.
• Documentation is much improved, including a built in API playground for learning how to use the API and sample code.

Upgrading from API v1

Our legacy API v1 is very different from our newer API, so there is no direct upgrade path. Many of the calls are similar, but you will likely have to rewrite a lot of your syncing code. However, the benefits are enormouse, including batch syncing, relaxed rate limitations and access to lits, outlines, collaboration and more.

Upgrading from API v2

Upgrading from API v2 to API v3 is easy. Most of the API calls will work unchanged. The notable difference is that "notebook" has been renamed "notes" so you'll need to change your URLs. If you read the "What's New" section above, you'll see all the changes that you'll need to account for.

The big change is with authentication. In v2 you would ask for the user's password which would give you total access to their account. But this sometimes makes users uneasy and your app was then responsible for maintaining the security of the account. You weren't storing their password in plain text where you ;) The new authenticate uses the industry standard OAuth2 flow which is more secure and allows you to request the permissions that you need instead of total access. This is where most of your time will be spent, but it's worth it for the user's security. There are existing libraries for all platforms that can make working with OAuth easier.