We programmers have a strange sense of humor about naming our intangible creations. You really have to wonder what goes through non-techie heads as they run across the battlefield of one of our wars of technical ideology.  Think about how that grandmother down the street hears “Eunuchs versus windows” — it sounds like some kind of hate crime party game.

As a programmer who wants to build more cool things, I’d like to offer my opinion on the REST vs. SOAP debate (to the dismay of mothers everywhere).

For the uninitiated bystander, REST and SOAP are fairly similar ways of letting different applications, services, and devices share data with each other.  For a quick example, let’s assume you track your household shopping list on a piece of paper under a magnet on your fridge.  One day you drive to the supermarket and realize that your list is still stuck to the fridge.  You can either wing it or have someone next to the list relay it to you over the phone.  If your shopping list was online you could pull it up from your phone at the store, but you could also do a lot other interesting things like allowing different services to tell you how healthy your menu was, to group the list by aisle for quick navigation at your nearest location, or to find the brands that are on sale.  That’s a big part of what REST and SOAP do, they allow people to create tools and “mashups” that find new uses for (or meaning from) existing data.

Very briefly (and quite biased and oversimplified):

• SOAP enforces order at the cost of flexibility.
• REST permits chaos for the benefit of flexibility.

Still with me?  How about this:

• SOAP requests are verbose with a lot of formal syntax, always dealing with an HTTP POST.
• REST is stateless and operates just like the Web where resources are at /paths/like/this.

When passionate developers release an API there’s usually anticipation and curiosity about the kinds of third-party aftermarket that will develop.  Those suburbs of development can make or break a project.

A problem that I’ve seen quite a bit from various web services lately (I’m looking at you, Pingdom) is one where developers get excited about checking off the “Web API” feature request (or marketing bullet point), but it’s clear that nobody on the official development team actually tried to build a new tool with it.

I sat down tonight and thought about the API design blunders that give me the most grief.  Let’s see how well you do!

Have a Web API you want the world to use?

• Don’t make me log in and log out through the API.  You can tell who I am from my API key in the HTTP headers, and you can authenticate me by comparing a checksum you generate on-the-fly against the one I provide in the headers.  By enforcing an explicit login you’re requiring me to send at least 2-3 packets (login, action, logout or timeout) when I should be sending one.  Perhaps that’s fine for a desktop application that can maintain a persistent connection, but we live in the age of iPhones on cellular networks.  Why limit your reach?  Why punish my phone?
• Don’t make me use the Web API with the same login and password that I use to access the normal app or service.  I shouldn’t have to give away all my secrets just to share some info with another application.  Issue me an anonymous API Key and allow me to use a secret phrase for signing my packets that is specific to the API access.
• Don’t use SOAP just because it’s a more familiar buzzword.  There’s no need to be so formal unless it’s absolutely necessary.  Formality robs XML of its flexibility and platform agnosticism.  It makes it a pain to reuse my data if my new platform requires another library (or worse, custom code) to play dress up and talk SOAP.
• Don’t forget to provide examples!  Documentation is well and good, but a block of sample data is worth a dozen pages of explanation.

Do you have an abnormal affection for, or allergy to, a particular Web API?  I’d love to hear about it in the comments.

-Jeff