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.

Old URL:

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

New URL:

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.