Skip to Main Content
Official App
Free – Google Play
FreshBooks is Loved by American Small Business Owners
FreshBooks is Loved by Canadian Small Business Owners
FreshBooks is Loved by Small Business Owners in the UK
Dev Blog

New: API Version Numbers, Better Paging

by vinegar 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>

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  us.