New: API Version Numbers, Better Paging

by Jaco on January 10, 2008

Afternoon gang! We’ve got a couple new API feature announcements to kick off 2008 - just 3 weeks after our last release.

Paging Metadata

Now when you submit an API request that returns more than one object (i.e. all *.list methods), you’ll also be returned paging metadata that describes the result set. This should help you better navigate large data sets returned by the API. Here’s a sample new response from invoice.list:

	<?xml version="1.0" encoding="utf-8">
	<response status="ok">
	  <invoices page="2" per_page="5" pages="8" total="37">
	    <invoice>...   </invoice>   
	       <invoice>...   </invoice>
	       <invoice>...   </invoice>
	       <invoice>...   </invoice>
	       <invoice>...   </invoice>  
	  </invoices>
	</response>

Now, we think this is a swell improvement, and our users have been pining for it. But it comes at a small cost – the introduction of these new top-level paging nodes could break existing integration code. This issue leads into our next announcement:

API Version Numbers

Now when you submit your API requests, you can optionally specify a version number as part of the request URL.

	 http:// mycompany.freshbooks. com/api/xml-in  

	 http:// mycompany.freshbooks. com/api/2.1/xml-in  

To take advantage of these new response formats, you must specify version 2.1 as part of the request URL. If you do not specify a version number, the API will return the old, less-descriptive response format (version 2.0).

Deprecation Warning!

We will support both versions (2.1 and 2.0) until March 1st, 2008. This will give you nearly 8 weeks to migrate your applications to the new schema.

If you have questions, comments or concerns, please contact us.