11436 SSO

Armrest & REST API Design

Brian Mulloy
Feb 07, 2012

Last week I flew from Doha, Qatar to Brussels, Belgium. The fella in the aisle seat fell asleep before takeoff. The road warrior code of chivalry indicates one should never wake a fellow traveler.

So I stayed in my window seat for 8 hours. After a few minutes it became obvious that my armrest (singular, my neighbor had usurped the other one) was uncomfortable.

Here's a picture of the armrest.

The armrest has many problems. The biggest: you can't rest your arm on it.

If you try to relax, your elbow gets sucked by gravity into the cutout and pinched unpleasantly by hard plastic. If you deal with the pain and fall asleep you will wake to find your ears exploding because you inadvertently cranked up the volume, the flight attendant will be tapping your shoulder asking why you paged him and your reading light will be shining in your dilated eyes.

The Airbus A330-200 in which I was traveling holds 250 people. That's 2,000 man hours of discomfort per flight injected into the universe because of bad design.

So, why does such an obviously bad, pain-inflicting design make it into the world?

Because it cost-effectively solves other, non-customer-related problems! In this case, it is a clever way to store the remote controller while still keeping it accessible to passengers. It’s also done in a way that doesn't require an expensive reworking of the interior: cut off part of the armrest, put a hole in it and reattach on a hinge. Done! In-air multimedia problem solved!

What does this have to do with REST APIs?

Even with the best of intentions, API teams often stop short of doing the right things for their customers. Customers of APIs are application developers. Application developers are smart, busy, and born to suffer (especially Objective-C developers, NSThatsADifferentTopic). But they are also often musicians, gamers and aesthetes. They are attracted to things like truth and beauty. And they are attracted to good, self-consistent API design.

So, why do API teams often stop short of delighting developers? Because the time and cost of learning to do the right things and getting them done often seems prohibitive! At Apigee, we share everything we learn on our blog, twitter @Apigee, YouTube, API Craft on Google Group, and in our webinars.

There's no reason to walk the road to creating a fantastic API alone. If you know of an API or an API team that's not doing things right or is trying to go it alone, please send them to us. We'll get them straightened out.

Scaling Microservices