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

Conceptual Integrity Part 1 ... or Why Committees Can't Do Doodly

Last night at DevTalk LA (that Geeky local book club), having finished our book, we read two articles. We do this in-between books, to allow members a little extra time to get the book in-hand. Next week, we'll start the eagerly anticipated RESTful Web APIs by Richardson & Amundsen.

Add caption

RESTful Web APIs

This book appears to be a complete rewrite of their earlier RESTFul Web Services (2007). It was, by universal acclamation of Dev Talk LA, one of the better books we've recently read, and advance opinion holds the re-write to take things on the next level and clear up all our questions.

The two articles can be (and should be!) read on-line here:

•  Design and Research by Paul Graham
•  Why Why Functional Programming Matters by Reg Braithwaite

We spent most of the time on Paul Graham's essay.

If you haven't read Paul Graham, you need to stop reading here and get on with it. Buy his book. Read his essays. Just do it. The short-version of why is this: Paul Graham is a twice-successful Startup enterpreneur who built his success upon technical excellence. He's a big proponent of the rapid development he found possible through the use of Lisp, of which his is an advocate and presently is designing/promoting Arc, a Lisp derivative of his own. But there are two additional factors that make him a compelling figure.

First, he's done something other than technology. He's also a painter. And the interplay of what he has learned from both shows clearly in his very insightful and reflective essays. Secondly, he understands, in a very no-nonsense way the value and importance of passion. From last nights essay, for instance, came this timeless quote:

To make something good, you have to be thinking, "wow, this is really great," not "what a piece of shit; those fools will love it." 

Which brings us to the point of today's essay.

Conceptual Integrity.

It's important.

Really important.

Paul Graham gets it, too.

As he puts it, (highlights mine)

Notice all this time I've been talking about "the designer." Design usually has to be under the control of a single person to be any good. And yet it seems to be possible for several people to collaborate on a research project. This seems to me one of the most interesting differences between research and design. 

There have been famous instances of collaboration in the arts, but most of them seem to have been cases of molecular bonding rather than nuclear fusion. In an opera it's common for one person to write the libretto and another to write the music. And during the Renaissance, journeymen from northern Europe were often employed to do the landscapes in the backgrounds of Italian paintings. But these aren't true collaborations. They're more like examples of Robert Frost's "good fences make good neighbors." You can stick instances of good design together, but within each individual project, one person has to be in control. 

I'm not saying that good design requires that one person think of everything. There's nothing more valuable than the advice of someone whose judgement you trust. But after the talking is done, the decision about what to do has to rest with one person.
Why is it that research can be done by collaborators and design can't? This is an interesting question. I don't know the answer. Perhaps, if design and research converge, the best research is also good design, and in fact can't be done by collaborators. A lot of the most famous scientists seem to have worked alone. [ed. note: see my "Never Hire The Greatest Scientist The World Has Ever Known"] But I don't know enough to say whether there is a pattern here. It could be simply that many famous scientists worked when collaboration was less common. 

Whatever the story is in the sciences, true collaboration seems to be vanishingly rare in the arts. Design by committee is a synonym for bad design. Why is that so? Is there some way to beat this limitation? 

I'm inclined to think there isn't-- that good design requires a dictator. One reason is that good design has to be all of a piece. Design is not just for humans, but for individual humans. If a design represents an idea that fits in one person's head, then the idea will fit in the user's head too.

I wanted to collect these ideas into one place and last night was a wonderful impetus to do so.  But this posting is already too long, so it looks like we have to kick off a series. And what a wonderful topic for a series! Conceptual Integrity. And, I'm very happy to have one of my heroes, Paul Graham, give as forceful and thoughtful a kickoff as could be imagined.

I Remain,

TheHackerCIO

The Tribulations of Developers

... more about the book our GeekyBookClub chose last time around. I'd have voted against it!

DevTalkLA at last Tuesday's meeting wrapped up the last chapter of Data & Reality, a supposed classic by William Kent. The book proved highly disappointing. It's a kind of skeptical look at data modeling. Skeptics are generally annoying. If data modeling can't be done (objectively), what kind of practical advice does he have to offer us for doing it? Why bother?

This, for example, is from his concluding chapter, entitled "Philosophy":

"So, at bottom, we come to this duality. In an absolute sense, there is no singular objective reality.  But we can share a common enough view of it for most of our working purposes, so that reality does appear to be objective and stable." [p. 149]

What rot! If there is no objective reality at the base, how the devil can anyone share a "common enough view" of such a non-existent-thing in order for it to magically appear to be a thing, let alone an objective and stable thing?

And if we operate on the (supposedly naive) view that there is an objective reality at the base of what we do, and we do this because we *have to*, then what is the point of removing the naiveté?

Anyway, luckily, this rubbish book is now behind the group. And, also, the side-bar conversations were stimulating as always.

In fact, the great lament of the book club was related to timing. One member noted that the next book, RESTFull Web APIs, which looks extremely promising, was wonderful, but he needed to have read it several months ago, when he encountered these issues!

And TheHackerCIO, also had similar experience, with the Java Performance Book. I came to know about the book through DevTalkLA, and when I got it I realized that the client I had been building a performance engineering environment for would have gotten an order of magnitude better job out of me, if only I had read the book at the time I began the project!

But, such lamentations, trials, and tribulations are part and parcel of the life of the Hacker. We can only know about what we know at the time we know it.

I Remain,

TheHackerCIO

A Book Club Rebooted ?!?!

This month, my local "Geeky Book Club," rebooted.

I thought about calling it a facelift, but the club was never in need of a facelift. It really just needed a little bit more modernization. It's a long-running book club! About two decades, standing,  -- or, rather -- sitting, from what I can tell.

Officially, it used to be called the LAJUG Study Group.  The Web Page for this monicker still sits there -- for a while, at least. But now, the links on this page point to the newly rebooted:

DevTalk LA

It's not merely a name change, or a face lift. The group has shifted from being focused on Java to a broader range of technology interests. It was natural, almost imperceptible shift, which you can see for yourself by perusing the extensive list of  past books:

Past Books Covered Before I Joined:

• Design Patterns Elements of Reusable Object-Oriented Software by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides
• Refactoring by Martin Fowler
• Concurrent Programming in Java Design Principles and Patterns by Doug Lea
• Java 2 Performance and Idiom Guide by Craig Larman and Rhett Guthrie
• Agile Software Development by Alistair Cockburn
• Bitter Java by Bruce Tate
• Patterns of Enterprise Application Architecture by Martin Fowler 
• Problem Frames by Michael Jackson
• J2EE AntiPatterns by Bill Dudney, Scott W. Thomas, David Osborne, and Bob Kiel
• Documenting Software Architectures: Views and Beyond by Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, and Judith Stafford
• Pragmatic Programmer by Andrew Hunt and David Thomas 
• Refactoring to Patterns by Joshua Keriesky
• Expert One-on-One J2EE Development without EJB by Rod Johnson and Juergen Hoeller
• Domain Driven Design by Eric Evans
• Agile Software Development Ecosystems by Jim HighSmith
• Joel on Software: And on Diverse and Occasionally Related Matters That Will Prove of Interest to Software Developers, Designers, and Managers, and to Those Who, Whether by Good Fortune or Ill Luck, Work with Them in Some Capacity by Joel Spolsky
• Effective Java Programming Language Guide by Joshua Bloch
• Effective Enterprise Java by Ted Neward
• Aspect-Oriented Software Development by Robert E. Filman
• Java Concurrency in Practice by Brian Goetz, Tim Peierls, Joshua Bloch, Joseph Bowbeer, David Holmes, Doug Lea
• Head First Design Patterns by Elisabeth & Eric Freeman, Bert Bates & Kathy Sierra
• Test Driven Development: By Example by Kent Beck
• Pragmatic Project Automation: How to Build, Deploy, and Monitor Java Apps by Mike Clark
• Implementation Patterns by Kent Beck
• Java Generics and Collections by Maurice Naftalin and Philip Wadler
• Programming Groovy by Venkat Subramaniam
• Founders at Work by Jessica Livingston
• Effective Java, 2nd edition by Joshua Bloch
• Enterprise Integration Patterns by Gregor Hohpe
• Java Persistence with Hibernate by Christian Bauer and Gavin King 

I joined the group shortly after returning to my birthplace, here in Sunny Silicon Beach. That put me on the list at this point:

Books Covered During My Participation:

• Programming the Semantic Web by Toby Segaran, Colin Evans, and Jamie Taylor
• Coders at Work by Peter Seibel
• Advanced SQL Programming Forth Edition by Joe Celko 
• Seven Languages Seven Weeks by Bruce A Tate
• Pragmatic Thinking and Learning by Andy Hung
• Scrum and XP from the Trenches by Henrik Kniberg
• Flow: The Psychology of Optimal Experience by Mihaly Csikszentmihalyi
• Restful Web Services by Leonard Richardson, Sam Ruby and David Heinemeier Hansson
• Java Performance by Charlie Hunt & Binu John
• The Cucumber Book: Behaviour-Driven Development for Testers and Developers (Pragmatic Programmers) by Matt Wynne and Aslak Hellesoy
• Data and Reality: A Timeless Perspective on Perceiving and Managing Information in Our Imprecise World, 3rd Edition by William Kent and Steve Hoberman

Next Book Upcoming

• About Face 3: The Essentials of Interaction Design by Alan Cooper 

One can easily see that the focus shifted almost exactly when I arrived. We covered the Semantic Web, Coder Stories, SQL, 7 different languages, Thinking, XP, Psychology!!!, REST, Cucumber, and Database Modelling problems. Only one book, on Java Performance was directly about Java!!! 

So, the name change merely reflects the present-day reality ... the changes that have taken effect ... we now have a wonderful discussion-based book club for developers in the local Los Angeles area. Please come and join us ...

I Remain,

TheHackerCIO