Tag Archives: development

The Well-Designed API

We have worked with many APIs here at Layer 7. And over time we’ve seen it all, ranging from the good to the bad. We even see the downright ugly. Now a good API is a beautiful thing; it encourages innovation, abstracts appropriately, and is designed with enough forethought that nobody needs to change it down the road. Resiliency is a good quality in an API. APIs are a little like cockroaches in that they will likely outlive the human race.

But what about the other ones? The ugly and bad ones? This is where developers could use some guidance.

Truth is, good API design isn’t really hard, but it’s not easy. One thing I point people to is Leonard Richardson’s Maturity Model for REST, which Martin Fowler explores in his blog. Now I’m not a REST purist by any means—truth is I’m as guilty of quick-and-dirty HTTP tunneling hacks as the next guy—but when you see the maturity phases laid out so succinctly, you can’t help but be inspired to move toward more “resourceful” thinking and maybe even learn to love HATEOS. Part of good API design is knowing what you should aspire to, and Richardson’s model is much more concise and accessible than Fielding’s thesis.

Another good source of advice is Joshua Bloch’s superb Google Tech Talk How to Design A Good API and Why it Matters. Bloch wrote what is arguably the most important book about Java ever written, and indeed his talk is about APIs using Java as the model. But don’t let that deter you; virtually everything Bloch discusses is as relevant to RESTful JSON-style APIs as it is to Java. Follow his advice, transpose it to you language of choice, and frame it with an understanding of where you want to land in the maturity model for REST, and you will end the day with great APIs.

Clouds On A Plane: VMware’s Micro Cloud Foundry Brings PaaS To My Laptop

On the eve of this week’s VMworld conference in Las Vegas, VMware announced that Micro Cloud Foundry is finally available for general distribution. This new offering is a completely self-contained instantiation of the company’s Cloud Foundry PaaS solution, which I wrote about earlier this spring. Micro Cloud Foundry comes packaged as a virtual machine, easily distributable on a USB key (as they proved at today’s session on this topic at VMworld), or as a quick download. The distribution is designed to run locally on your laptop without any external dependencies. This allows developers to code and test Cloud Foundry apps offline, and deploy these to the cloud with little more than some simple scripting. This may be the killer app PaaS needs to be taken seriously by the development community.

The reason Micro Cloud Foundry appeals to me is that it fits well with my own coding style (at least for the small amount of development I still find time to do). My work seems to divide into two different buckets consisting of those things I do locally, and the things I do in the cloud. More often than not, things find themselves in one bucket or the other because of how well the tooling supports my work style for the task at hand.

As a case in point, I always build presentations locally using PowerPoint. If you’ve ever seen one of my presentations, you hopefully remember a lot of pictures and illustrations, and not a lot of bullet points. I’m something of a frustrated graphic designer. I lack any formal training, but I suppose that I share some of the work style of a real designer—notably intense focus, iterative development, and lots of experimentation.

Developing a highly graphic presentation is the kind of work that relies as much on tool capability as it does on user expertise. But most of all, it demands a highly responsive experience. Nothing kills my design cycle like latency. I have never seen a cloud-based tool for presentations that meets all of my needs, so for the foreseeable future, local PowerPoint will remain my illustration tool of choice.

I find that software development is a little like presentation design. It responds well to intense focus and enjoys a very iterative style. And like graphic design, coding is a discipline that demands instantaneous feedback. Sometimes I write applications in a simple text editor, but when I can, I much prefer the power of a full IDE. Sometimes I think that IntelliJ IDEA is the smartest guy in the room. So for many of the same reasons I prefer local PowerPoint for presentations, so too I prefer a local IDE with few if any external dependencies for software development.

What I’ve discovered is that I don’t want to develop in the cloud; but I do want to use cloud services and probably deploy my application into the cloud. I want a local cloud I can work on offline without any external dependency. (In truth, I really do code on airplanes—indeed some of my best work takes place at 35,000 feet.) Once I’m ready to deploy, I want to migrate my app into the cloud without modifying the underlying code.

Until recently, this was hard to do. But it sounds like Micro Cloud Foundry is just what I have been looking for. More on this topic once I’ve had a chance to dig deeply into it.

The API Lab

Promotion is a problem faced by every API developer. Long nights of coding have given form to the stroke of genius you had six months ago in the cafe. You’ve just written the API that will serve as the front door into your application. But how do you document this so that your peers will use it—and hopefully make you rich in the process?

Java had Javadoc, an innovation that managed to strike a surprisingly effective balance between ease of use and systematization (three cheers for strong typing and static binding). Web services “solved” the interface definition problem with WSDL, a standard only its authors could love (and some of these won’t admit to participating in conception). To the registry crowd was left the task of devising clever ways to document a SOAP API around the torturous abstractions of WSDL so that humans could grok it as effectively as the machines. Few would argue that their solutions were, well, solutions.

RESTful APIs neither benefit nor suffer from formalized approach and automation. Every so often WADL pokes its head up, only to be knocked decisively back into its hole in a community game of Standards-Whac-A-Mole. REST is—and indeed, has always been—a style that resists any formalism that threatens its simplicity and accessibility. For this, above all, the community deserves praise.

But this does leave a hole around documentation. APIs tend to be described-by-wiki, which can be great or just awful, depending on a developer’s ability to write and discipline to update. Good ideas like ProgrammableWeb showcase both of these extremes; however, the site suffers in particular from out-of-date API descriptions which is too bad.

Outside of the eventual acceptance en masse of some kind of standardized wiki template for APIs (which I think is actually quite likely), we probably won’t see substantial change in API documentation soon. Minor changes, though, can still count for a lot, and it’s worth pointing these out.

Google, always an innovator to watch, create a lot of APIs. They recently published the Periodic Table of Google APIs, which as its name suggests is a clever way to visually categorize their API portfolio into groups like mobile, data, geo, etc. It’s a bit gimmicky, but it is also fun and actually inspired me to try some new Google APIs that I wasn’t aware of before.

So, isn’t it about time for more creative solutions around API documentation?

What Will Be The Future of Application Development in Cloud Computing?

Peter asks this important question over on the eBizQ forum. This is a topic I’m really interested in, and my rather long winded answer is here.

A Brief, Incomplete, and Mostly Wrong History of Programming Languages

Alex Cruise (who is obsessed with Scala) sent me this awesome history of programming post by James Iry.

I think my favorite entry is this one:

1972 – Dennis Ritchie invents a powerful gun that shoots both forward and backward simultaneously. Not satisfied with the number of deaths and permanent maimings from that invention he invents C and Unix.

I really found the time line interesting. I honestly wouldn’t have guessed Ruby was that old. Everyone thinks of the 70s as such a fertile time in language development (everyone who was anyone came up with a language), but we easily forget the important milestones in the 50s. Half a century later we are still dealing with some of the decisions made in this time.