Huddle ~ Work Better Together

Api Drop II: Making Good Shape

I’ve been working on the API so far this iteration. It’s been a lot of fun. The interesting thing about writing an API or a framework is that it forces you to think hard about the public interface of your work. Maintaining Good Shape) in a public interface is always important for an OO programmer, but when the public interface IS the end-product, it shifts the emphasis of your code.

(image used under CC attribution license)

Working on the API for Huddle is an enjoyable exercise in Defensive Programming. I’ve had to use some pretty dire “APIs” in my time, and we’re anxious not to inflict anything like that on you guys. The goal I’m working toward is that, should something go wrong and we can’t fulfil a request:

a) common web clients should behave in a sane way by default (particularly browsers, but if you’re targetting something specific talk to us)
b) we let you know exactly what went wrong, at the right level of abstraction, so that you know how to fix it.

I’m driving out the implementation of what I write with a set of tests that call the API’s methods and check their responses. This works well, because the implementation is just a thin wrapper of error handling over existing domain services. We’ve been using TinyGet for this, and it’s a joy to play with. The biggest changes, in no particular order:

Discussions are available over the API! Anto has put together the first cut of this, and I’m really happy with how quickly we’ve been able to expose this functionality. The discussions are the first feature we’ve built with our New Set of Best Architectural Practice Core Values ™ and the patterns we’ve used have really paid off. If you want to provide a simple message board or shoutbox on your site, you can build on ours, with your own UI. Sweet :) Your users will all require Huddle.Net accounts, obviously (at least until we allow public workspaces), but hey – they’re free.

This time round, we’re using Basic HTTP Authentication – there wasn’t any good reason not to use HTTP Auth in the first place, but a custom username/password header genuinely seemed like a good idea at the time. Early feedback said it was probably a bad idea, and we’ve upped our caffeine levels accordingly. My particular apologies to the guy writing the plugin for a certain Word processing package.

We’re now allowing file downloads through the API – sorry it wasn’t in the first drop, but we had other things to ship (that I’m not allowed to talk about yet). You can now access a file’s content at api.huddle.net/files/{file-id}/download

We’re adding (I believe) the MIME-Type field to our file listings, which makes it much easier to be clever about file handling. This should be doubly useful if we decide to provide file thumbnails through the API.

We’ve tightened up the responses that we send back to the caller: many things that used to fail with a 500 now return an appropriate HTTP response. I’m still not sure about this half JSON-RPC, half REST combo we’re putting together but it IS simple, and it DOES seem to be working. Going forward, we’ll try to use the following codes consistently:

• 301: We know what you mean, but the URI has moved. We’ll try to get breaking URI changes covered by a 301, and we’ll use this to redirect you to SSL if you come over http.
• 400: Bad request. If you send us a malformed request, an invalid parameter etc.
• 401: If we don’t seem to have any valid auth details from you.
• 403: If auth details are incorrect, OR the item is locked by a security constraint of some kind. The response should contain a useful error message and if it doesn’t, tell us. I don’t like the ambiguity here, and nor does our l33t Web Ninja.
• 404: No valid resource available. If you try to access a file, workspace etc. that does not exist.
• 410: Gone. If you try to access a resource that’s been deleted.

• 200: Successful. When a GET request succeeds
• 201: Created. When you create a new file, workspace, discussion etc. The response will contain a URI and ID for the newly created entity.

I’m going to print out the REST for Toddlers guide to status codes, because it’s at about my level of understanding. The list will get longer as we support more varied operations, and we’ll flesh out fuller and more specific documentation next iteration.

I’m against adding custom error numbering schemes without cause, but Nick thinks API developers will gain from more granular information. If you’ve got any preferences (and if you’re still reading, congratulations: I officially love you) then drop us a line at the usual address

I’m particularly interested to hear any ideas that people have on the status codes and responses for failures to update or create resources. Designing good validation on top of an API that returns no data is a pain, and just sending back a plain-text error message has localization and maintenance implications. If you’ve got specific requirements for what happens when your CRUD POSTs fail, get in touch.