New: API Version Numbers, Better Paging
Afternoon gang! We’ve got a couple new API feature announcements to kick off 2008 – just 3 weeks after our last release.
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).
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.