Developer's API Documentation : Notebook


Syncing

If you use the following recommendations you can sync notebooks cleanly and efficiently. One of the most important things is to use the "lastedit_notebook" and "lastdelete_notebook" timestamps, returned from Account Info, to determine if any changes have happened on the server before you fetch anything. In the vast majority of cases, when syncing, nothing will have changed on the server and you won't even need to do anything.

Sync Flowchart


Notebook Datatypes

There are a number of fields that can be set or retrieved when working with notebooks. Here is a description of these fields.



Retrieving Notebooks

The "notebooks/get.php" API call will return a list of the notebooks that match your search parameters. You can access this via GET or POST. The following search parameters may be used to limit the returned notebooks. To make sync go as efficiently as possible you should request the minimum amount of data that you need. Usually, this means keeping track of the "lastedit_notebook" field from the account/get.php API call and using this in combination with the "modafter" field in this call to request only those notebooks that have changed since your last sync.


http://api.toodledo.com/2/notebooks/get.php?key=YourKey;modafter=1234567890

This returns a list of notebooks in the JSON format, like this.

JSON: 
[{"num":"2","total":"2"}, {"id":"1234","title":"My Ideas","modified":1281990824,
"added":1281990824,"folder":"123","private":"0","text":"The text of my notebook"},
{"id":"1234","title":"Favorite Movies","modified":1281990824,
"added":1281990824,"folder":"123","private":"0","text":"Star Wars"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/notebooks/get.php?key=YourKey;modafter=1234567890;
fields=folder,star,priority;f=xml

XML: 
<notebooks num="2" total="2">
	<notebook>
		<id>1234</id>
		<title>My Ideas</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>The text of my notebook</text>
	</notebook>
	<notebook>
		<id>1235</id>
		<title>Favorite Movies</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>Star Wars</text>
	</notebook>
</notebooks>

Adding Notebooks

You can add up to 50 notebooks at a time by making a POST to the "notebooks/add.php" API call. You can set the following fields: title, folder, private, added, text.

There is also a special field called "ref" that you can use to pass through an id number to aid in matching things up after a sync. The "ref" field is not saved into the notebook, it is only echoed back to you on this call.

Notebooks are added by creating a JSON object (example below) and submitting a POST to the API. Be sure to encode the data properly for transfer via a URL (symbols replaced with their %XX equivalent and spaces encoded as +). Each element in the array will be a notebook object. You only need to set the fields that you want to set. For efficiency, you should try to send only the fields that you are setting.

http://api.toodledo.com/2/notebooks/add.php?key=YourKey;
notebooks=[{"title"%3A"My Ideas"}%2C{"title"%3A"Favorite Movies"%2C
"folder"%3A"123"%2C"text"%3A"Star Wars"%2C"ref"%3A"98765"}]

If the action was successful the added notebooks will be returned in the same order in which they were added. If there were any errors on individual notebooks, they will be output inline with the returned notebooks, so you can determine which action failed.

JSON: 
[{"num":"2","total":"2"}, {"id":"1234","title":"My Ideas","modified":1281990824,
"added":1281990824,"folder":"123","private":"0","text":"The text of my notebook"},
{"id":"1234","title":"Favorite Movies","modified":1281990824,
"added":1281990824,"folder":"123","private":"0","text":"Star Wars","ref":"98765"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/notebooks/add.php?key=YourKey;
notebooks=[{"title"%3A"My Ideas"}%2C{"title"%3A"Favorite Movies"%2C
"folder"%3A"123"%2C"text"%3A"Star Wars"%2C"ref"%3A"98765"}]


XML: 
<notebooks>
	<notebook>
		<id>1234</id>
		<title>My Ideas</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>The text of my notebook</text>
	</notebook>
	<notebook>
		<id>1235</id>
		<title>Favorite Movies</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>Star Wars</text>
		<ref>98765</ref>
	</notebook>
</notebooks>

Editing Notebooks

You can edit up to 50 notebooks at a time by making a POST to the "notebooks/edit.php" API call. The id field is required, and the following fields are optional: title, folder, private, text (see above for possible values).

Notebooks are added by creating a JSON object (example below) and submitting a POST to the API. Be sure to encode the data properly for transfer via a URL (symbols replaced with their %XX equivalent and spaces encoded as +). Each element in the array will be a notebook object. You only need to set the fields that you want to edit. For efficiency, you should try to send only the fields that have changed.

http://api.toodledo.com/2/notebooks/edit.php?key=YourKey;
notebooks=[{"id"%3A"1234"%2C"title"%3A"My Note"}%2C
{"id"%3A"1235"%2C"title"%3A"Favorite Movie"%2C"folder"%3A"123"}];f=xml

If the action was successful the edit notebooks will be returned. If there were any errors on individual notebooks, they will be output inline with the returned notebooks, so you can determine which action failed.

JSON: 
[{"num":"2","total":"2"}, {"id":"1234","title":"My Ideas","modified":1281990824,
"added":1281990824,"folder":"123","private":"0","text":"The text of my notebook"},
{"id":"1234","title":"Favorite Movies","modified":1281990824,
"added":1281990824,"folder":"123","private":"0","text":"Star Wars"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/notebooks/edit.php?key=YourKey;
notebooks=[{"id"%3A"1234"%2C"title"%3A"My Note"}%2C
{"id"%3A"1235"%2C"title"%3A"Favorite Movie"%2C"folder"%3A"123"}];f=xml

XML: 
<notebooks>
	<notebook>
		<id>1234</id>
		<title>My Note</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>The text of my notebook</text>
	</notebook>
	<notebook>
		<id>1235</id>
		<title>Favorite Movie</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>Star Wars</text>
	</notebook>
</notebooks>

Deleting Notebooks

The "/notebooks/delete.php" API call will allow you to permanently delete up to 50 notebooks at a time. You can access this via GET or POST.

Notebooks are deleted by submitting a JSON encoded array of id numbers to the API.

http://api.toodledo.com/2/notebooks/delete.php?key=YourKey;notebooks=["1234"%2C"1235"]

If the action was successful the deleted notebooks's id numbers will be returned. If there were any errors on individual notebooks, they will be output inline with the returned notebooks, so you can determine which action failed.

JSON: 
[{"id":"1234"},{"id":"1235"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/notebooks/delete.php?key=YourKey;notebooks=["1234"%2C"1235"];f=xml

XML: 
<deleted>
	<id>1234</id>
	<id>1235</id>
</deleted>

Get Deleted Notebooks

The "/notebooks/deleted.php" API call will enable you to detect when a notebook was deleted on Toodledo, so you can also delete the notebook from your application. You can access this via GET or POST.


http://api.toodledo.com/2/notebooks/deleted.php;key=YourKey;after=1234567890

This returns a list of id numbers and datetime stamps.

JSON: 
[{"num":"24"},{"id":"1234","stamp":"1234567891"},{"id":"1235","stamp":"1234567892"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/notebooks/deleted.php?key=YourKey;after=1234567890;f=xml

XML: 
<deleted num="2">
	<notebook>
	<id>12345</id>
	<stamp>1234567891</stamp>
	</notebook>
	<notebook>
	<id>67890</id>
	<stamp>1234567892</stamp>
	</notebook>
</deleted>

Error Codes

Any of the API calls can return error messages. Here is a list of the error messages that you may receive from the goals API.



Examples:
JSON:
{"errorCode":1,"errorDesc":"Empty key"}


XML:
<error id="5">The notebook title cannot be blank</error>
Toodledo.com | API Home | Forums | Contact Us | News | Privacy | Terms | Copyright © 2006-2011  4