A Good API is Hard to Find

API design was the GeekyBookClub topic last night atDev Talk LA. 

RESTful Web APIs is the current book, and we had a near overflow turnout for the discussion of chapters 2 and 3.

The book is turning out to be good. But it's the give-and-take of the group that really makes the club work!

Some members have worked ahead, which gives them a bit of an unfair advantage, but TheHackerCIO won't hold that against them. :-)

I particularly liked the fact that the author jumped right in with an actual API to take a look at. A Simple API (chapter 2), in fact, is a micro-blogging API that he uses to illustrate his points. He suggested using wget as a command-line tool to play with it.

I found that I don't have wget available on my MacbookProRetina.

As I mentioned to the group. When someone asks you how long something is going to take, always ask them, "Is this an estimate, or a commitment?" Because management needs to be reminded of this. A lot! Anyway, I curl-ed wget, but I couldn't get it to build because my Xcode was a version or two out, and that download/install seemed to be taking plenty of time. What should have been a 10 minute diversion threw me off for a half hour.

I switched over to simply using Advanced Rest Client, a Chrome extension I highly recommend! You can issue whatever RESTfull calls you wish, with any verb you please, graphically from within your browser, and you can even keep them organized in a file structure for reuse. A very handy tool.

There were too many take-aways from the discussion, but some of the biggest for me were:

1. Being Liberated by Constraints. As the author notes, constraining your REST design, for instance, by using his "personal standard," which requires the JSON to follow some structure, can indeed keep your developers from going wild.

2. I never knew about LINK and UNLINK, but they seem worthwhile. We talked for a while about how POST should be probably be used to create the resource, perhaps with an embedded link to whatever other resource is this resource-target. But then LINK can be used to create a further relationship, going the other direction, from target back to the dependent. (I may be missing something here, because the author tell's me he's going to fill me in on Chapter 11. )

3. PATCH -- looks like a performance enhancement. I'd say to avoid it until absolutely necessary, because it's not idempotent. You're only going to patch a portion of a representation, rather than replacing the whole thing.

4. OPTIONS -- we need to ALL be using this, and straight off the bat, to get the full "billboard" of what we can and should be able to do with our API. No one does. But that doesn't mean we shouldn't start!

5. Overloaded POST -- The author points out how on the web APIs we use POST is overloaded with anything and everything. As he put's it:

The HTTP specification says that POST can be used for:

 Providing a block of data, such as the result of submitting a form, to a data-handling process.

That 'data-handling process' can be anything. It's legal to send any data whatsoever as part of a POST request, for any purpose at all. The definition is so vague that a POST request really has no protocol semantics at all, POST doesn't really mean 'create a new resource'; it means, 'whatever.' [p. 41]

And "Whatever", is never a good thing to mean.

 So don't mean that.

And restrict your POST to creation of new resources with newly-created identifiers.

I Remain,

TheHackerCIO