Secret API Tips

Send those pesky parameters as GET variables

Don't tell anyone but being fellow developers we decided to make your life easier and allow you to optionally pass parameters to the API using standard FORM and GET variables. What does that mean exactly?... well it means you could call the following:

http://[yoursite]/projects/111/milestones.json?find=upcoming

instead of having to post the find option in the request body.

See how much we care? We want to make your life easier....


Send XML instead of JSON

If you like Star Trek and propellers you can retrieve XML formatted responses just by switching the .json extension to .xml.

eg. Call /projects.xml instead of /projects.json

You must also send all your body posts as XML if you're going down the XML route! So instead of:

{
	"todo-item":{
		"notify":true,
		"responsible_party":1,
		"content":"Yippe ay yay",
		"due-at":"20100813"
	}
}

you could post:

<request>
	<todo-item>
		<notify>true</notify>
		<responsible_party>1</responsible_party>
		<content>Yippe ay yay</content>
		<due-at>20100813</due-at>
	</todo-item>
</request>


Funky Date Formats

OK, we made an interesting decision regarding dates - It makes sense to return some items as very specific points in time (such as the exact moment when a task was completed), but other dates are dependant on the users current timezone.

Because of this we return all specific date times in Zulu time format YYYY-MM-DDThh:mm:ssZ eg. 2014-08-12T10:30:00Z and other dates like due-dates as simple YYYYMMDD eg 20110812.


Use ETags

ETags are cool. They save bandwidth and are easy to implement. Most calls back from our API include header named etag.

When you make your next GET call to the API, send this etag up in a Request Header called If-None-Match


Easily get ID of new items

Because we are such nice guys, we always return both the location URL AND ID of any newly created items in the response header.  So when you post a new task for example, the ID of the task in available in the headers returns as id - for consistency we always use id