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

Some REST for the Wicked

The wicked coders at Dev Talk LA started a REST book the night before last. Discussion was amazing. First we covered the paper on functional programming, which we didn't get to last week. This paper is a response to another paper, so you should read both. Then we did chapter 1 of the REST book.

One fellow geek brought his date to the Meetup -- this was his date night entertainment! I hate getting pushed off my UberGeek pedestal, but stuff happens! I look forward to seeing the happy couple at future Meetups.

I was kind of blindsided by one discussion, which mentioned "traits" with Java. I never heard of them. That's pretty weird for a java techno-maven such as myself, so I need to follow that up with him. And Google didn't help me out this morning, either. It seems "traits" might be another term for "mixins," which were found in some OO environments, but never in Java. Mixins were/are a kind of inheritance where multiple inheritance didn't quite fit the bill. I'm not sure if he's thinking of AOP and mixing the notion in with traits, but it's something to check up on. Or it could be some kind of a library that offers this kind of support in the java ecosystem.

Someone else mentioned GPars, a concurrency framework used in Groovy quite a bit. I don't know that much about Groovy, so this one  has to be put down on my "to be investigated list." I already spent a few minutes Googling it, and it appears to be an implementation of the "actors" abstraction from Scala and Erlang, but in the Groovy/Java world. I definitely need to spend some time playing with Groovy and taking advantage of it's type-inferencing, so I can avoid boilerplate code more. That just needs to happen. Because speed matters.

Another member highly recommended a concurrency talk by Doug Lea. From what he said, I believe that this is the talk.

Moving on to the REST book, the bid system got completely hijacked! Normally, everyone offers page "bids," and the lowest bid wins. But this time, one of our members just jumped in and pushed the last page of the chapter as the opening round!

The discussion focused on a Members key problem with REST for him in his work and in general., which was to get the human readable and machine readable representations integrated. For instance, he hates the whole embedding of versions into the URL for APIs. This is ugly and hard to support. Instead, if you traverse from the top of the hierarchy, and have clients parse a page of "billboard" information, which describes the kinds of additional services and methods available in the API (at that version), then you can completely avoid this.  You are basically building the API spec into the page returned, which the client reads, scrapes, and uses to invoke the various additional API calls.

The problem is, this scheme doesn't allow permalinks and the use of bookmarked pages in the browser. You have to start at the top of the hierarchy and traverse it, because the site might have been reorganized since the last time your client noted a permalink.

But it occurred to us that you could have a versionless permalink API, that mapped permalinks to whatever new, reorganized location they now properly dwelt in. And that would effectively take care of most of the whole issue.

We still need to get our heads wrapped around the right way to do all of this, but the book promises to help us immensely in that regards.

I Remain,

TheHackerCIO