Hello there Developers.  My names Dan.  I’m new developer on the API team! I’ve been lurking in the shadows, answering your support questions, getting up to speed on the back-end here at FreshBooks.

Now that the training wheels are off I’m going to be roaming around the API with Mike.  Keep your eyes peeled for fresh new integrations and additions to the API. We’ll be tackling things that are brought to our attention here on the blog as well as over at the developer community.

The new <auth_url /> requires an authorized session to work, and is intended to provide an administrative link to your target object.  Since we didn’t have a client <url /> element in the client.get response, we’ve included that for consistency.

<auth_url /> will honour an existing administrative session, if you have already logged into the application in some way. It will NOT auto-magically direct you to a secure administrative page without prompting you for user and password if you haven’t already logged in.  So don’t get’em mixed.  <url /> is for client links, <auth_url /> is for you.

Summary:

• client.get:
  • <url /> added to response
  • <auth_url /> added to response
• estimate.get:
  • <auth_url /> added to response
• invoice.get:
  • <auth_url /> added to response

Our API documentation has been updated to include this element where necessary.

Since I’m the second Mike in the office, I’ve been barraged with nicknames since I joined up.  Because my last name is Gauthier, there are a few variations I will respond to.  Mikey G or MG would work.  G-man?  Michael?  Embarrassing.  But since Mike McDerment doesn’t really post on the Developers blog, I can hope and dream of being just ‘Mike’ again.  We can keep that between us.

From here on in, we intend to post more frequently than we have.  Our last blog post was in June, and that’s just not cool.  Also, please feel free to get in touch with us via the developer forum.  My teammate Dan (introduction forthcoming) and I will be actively monitoring our community and addressing developments and concerns both here and there.

• Andrew finally had enough of seeing people enjoy the OSX widget and wrote a time-tracking gadget for the Vista Sidebar based off of the OSX widget! Not only does our widget provide a place for others to start, but we’re also going to help Andrew make it look pretty.
• Joel has written GetFresh, a new way for your clients to log into their FreshBooks accounts in order to pay you faster. For a small fee, you can download and configure the app, then send it to your customers. They can fill in their username and password, and with 2 clicks can be logged right into FreshBooks. Joel’s also included a screencast showing how to configure things.

Remember that the above apps are from 3rd parties, and FreshBooks is not responsible for their content or functionality. We’re just happy that people are building useful things for everyone, and want to share the news with everyone.

If you’ve got an idea for a widget, gadget, app, or script that would make your life easier, all I can say is that there is no time like the present. The API is here, it’s alive, and I’ll be kicking it into shape for you.

Once you’ve got your app running, you can count on us to take notice, and let everyone know about the excellent job you’ve done. We’re rooting for you!

Notable features

• Each staff member receives a unique API token, just like the admin user. This identifies the staff member for any actions he or she takes via the API.
• We speak the same great API for both staff and the admin account! This means that time trackers that work with the admin account should continue to work seamlessly for your staff members.
• We respect the access restrictions you’ve set. Your staff members will be able to view and edit the same information (no more, and no less) through the API as they would be able through the application itself.
• This change shouldn’t affect any API applications you already had running. If it does, let us know!

How to find your staff token

First of all, the admin user has to enable the FreshBooks API. Then any staff member can browse over to his or her Profile page (link at the top, beside Help and Logout). The token and access URL will be displayed at the bottom of the page. The admin user can also find any staff member’s token, by Editing the staff member in question.

Caveats

Of course, there are always caveats. In order to release this feature as soon as possible for your use–while maintaining the same security you expect from FreshBooks–we’ve only implemented the client, project, task, and time_entry API methods. Staff members trying to access unimplemented features will receive an API error response.

And more!

We’ve made a few other updates to the API:

• client.get now returns the client’s current credit balance
• project.list and task.list now only return active, non-archived items, just like you expect when tracking time in your browser.

We’ll be updating the API docs today to reflect these changes. So go forth and track time, and let us know what you think. Enjoy!

Portability

While the FreshBooks widget is currently only for OSX’s Dashboard, a lot of the HTML element access and glitzy fades are pure jQuery, and should be portable to other widget facilities, and the FreshBooks website itself. It’s also nice to be able to use the same skills in widget creation as webpage creation.

Power

The $() construct is much, much more powerful than it at first appears. Take a closer look at the full power of selectors to see what I mean. And the skills you learn are re-usable, since jQuery implements CSS3-style selectors. When browsers get around to fully supporting them, you’ll already be at home. In addition, jQuery also makes dealing with XML (as returned by the FreshBooks API) and Ajax in general a whole lot easier!

Conciseness

jQuery also leads to shorter, more concise JavaScript. $("#submit") is so much easier to type than document.getElementById("submit"), and infinitely more flexible when you want to, say, operate on all of the images in a page with $("img"). You “chain” together various jQuery commands, such as css() and show() simply by applying them to the returned “wrapped set”, like $("img").css('opacity',0.5).

Peer Pressure

Apparently I’m not the only one who thought this would be a good idea. I just recently noticed an awesome SVN notifier widget which also includes jQuery. Perhaps the idea is catching on…

• invoice.get and invoice.list now return <recurring_id/>
• project.list can now be filtered by <task_id/>
• time_entry.create rounds hour values to hundredths of an hour (just like the web interface)
• Raised maximum request limit to 5000 requests/day
• A handful of other bug fixes and tweaks

As always, if you have questions or comments, please let us know on the developer forums.

Of course, the first step was to look at the page source. However, the page source looked entirely correct. All of the form elements were defined in the correct places, with the expected order. This is where fantastic tools like Web Inspector (found in the Safari Debug menu) and Firebug come in handy. On reproducing the bug, I managed to SEE the offending tag in its new location in the Web Inspector view. A whole set of input tags sitting at the start of a table!

It turns out that if you replace a table inside a div tag, Safari does some reparsing of your provided HTML. Say, you put a hidden input tag within a tr, but outside of a td. Normally this works fine, and document.forms[0].elements[] shows up in the way you’d expect. But when replacing the table via something like innerHTML, it barfs because the ONLY things allowed in a tr tag are th or td. Thus speaks the XHTML 1.0 transitional DTD:

<!ELEMENT tr (th|td)+>

What appears to happen, is that any input elements outside of a td get bubbled up the DOM until they find a place where they are allowed…in this case, immediately before the enclosing table.

Hence, you get strange results with:

myDiv.innerHTML = "<table border='1'><tbody>" +
"<tr><td><input type='text' value='First'></td>" +
" <input type='text' value='Second'></tr>" +
"</tbody></table>";

But not with:

myDiv.innerHTML = "<table border='1'><tbody>" +
"<tr><td><input type='text' value='First'>" +
" <input type='text' value='Second'></td></tr>" +
"</tbody></table>";

Hence, when adding form elements improperly, programmatically, and referencing them with document.forms[].elements[], you get Very Strange results.

So please, for your own sanity’s sake, nest your elements properly!

Yesterday I was merrily coding away, creating Cool New Features for you, our FreshBooks users. After adding 4 innocent lines of code, I started to see raw JavaScript instead of the beautifully formatted FreshBooks interface we all love. This led me through the following hoops:

1. There’s no trailing <script> tag in the page source. So that’s why I saw raw JavaScript.
2. Apache’s error.log showed dying processes!
3. Reconfiguring Apache to use only one child thread, I attached gdb and recreated it…and caught PHP dying of a segmentation fault!
4. At this point I think I’ve found a bug in PHP (since progams should never ever segfault).
5. Then I discovered I made the classic error of pasting-without-looking, and inadvertently created an infinite recursion!, and found a bug report that indicates that this is “working as designed” in PHP. *cough*

To wit, I proceeded to see how other scripting languages handle infinite recursion. Here are the results…

PHP

$ php -r "function f(){f();}f();"
Segmentation fault

Dies an untimely death, because each function invocation recursively calls execute():

In my opinion, a well-behaved program should NEVER segfault, because a segmentation is only rarely the first bad thing that’s happened (it’s just the most fatal one to the process in question). But let’s see if anyone else does better…

Perl

$ perl -e "sub f{&f;}&f;"
Killed

Runs the system out of memory (all 256MB RAM + 400MB swap in my Linux VMWare image). While this is horrible from a denial-of-service perspective, it’s easy to prevent by setting ulimit on the server processes. And it shows that Perl isn’t artificially limiting recursion depth; if you’ve got the RAM, you can go to infinity (almost).

Python

$ python -c "def f(): f()
f()"
Traceback (most recent call last):
  File "<string>", line 2, in <module>
  File "<string>", line 1, in f
...
RuntimeError: maximum recursion depth exceeded

YAY! A useful result. Of course it indicates that you may have problems recursing deeply. See below for alternatives…

Ruby

$ ruby -e "def f
  f()
end
f()"
-e:2:in `f': stack level too deep (SystemStackError)
	from -e:2:in `f'
	from -e:4

Also an excellent, useful error message!

Tail Recursion

Of course, if you wanted to loop infinitely, you’d be much better off using a language that supports tail call optimization. Something like Scheme, Lua, Erlang, etc. Even better, you can write your own language that supports tail call optimization (take a look at the last chapter of Structure and Interpretation of Computer Programs, and section 5.1.4 in particular). However, since choosing (or writing) a different language is not always feasible, people are always coming up with creative solutions in languages that don’t support TCO!

For those with a practical bent

Not willing to give this up just yet, here’s a set of less artificial examples:

<?
//php
function f($x) {
	if ($x == 1) return 1;
	return ($x + f($x-1));
}
echo f(1) . "\n";
echo f(10) . "\n";
echo f(100) . "\n";
echo f(1000) . "\n";
echo f(10000) . "\n";
echo f(100000) . "\n"; // Segmentation fault
?>

#perl
sub f {
	my $x = shift;
	if ($x == 1) {return 1;}
	return ($x + f($x-1));
}
print(f(1) . "\n");
print(f(10) . "\n");
print(f(100) . "\n");
print(f(1000) . "\n");
print(f(10000) . "\n");
print(f(100000) . "\n");
print(f(1000000) . "\n");
print(f(10000000) . "\n"); # malloc: *** mmap(size=351752192) failed

#python
def f(x):
	if x == 1: return 1
	return x + f(x-1)

f(1)
f(10)
f(100)
f(1000) # maximum recursion depth exceeded

#ruby
def f(x)
	x == 1 ? x : x + f(x-1)
end
puts f(1)
puts f(10)
puts f(100)
puts f(1000)
puts f(10000) # stack level too deep

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.