The Good, the Bad, and the Ugly of REST APIs

| by Boris Lublinsky on Jun 10, 2011. Estimated reading time: 3 minutes |


On the heels of an interesting REST discussion at InfoQ there is an interesting post from George Reese - The Good, the Bad, and the Ugly of REST APIs, discussing many Dos and Don’ts of REST APIs development.

Among good practices for REST API creation, Reese emphasizes the following:

  • Map your API model to the way your data is consumed, not your data/object model.
    The data in your API calls should not look like highly normalized representations of database tables. They should represent a model of the data in a way that makes sense to API consumers.

    This is similar to the SOA principle of separating messaging model from the underlying data access model

  • Meaningful error messages help a lot. When building an API, it is necessary
    to think about all the mistakes people can make when learning to use your API,

    returning a detailed explanation of what exactly was done wrong. Some good examples of such messages are presented in a great slide show.

  • Providing solid API documentation reduces need for external help.
    Solid API documentation enables an individual to both understand the simple examples that help them get started as well as the complex ways in which they can leverage the API to accomplish advanced tasks
  • Use an appropriate security APIs. For example, Reese points out that OAuth authentication, often used with REST, works well when an API provides a target content for the browser, but is rarely applicable for system-to-system interaction. More discussion on securing REST APIs can be found at "RESTful API Authentication Schemes"
  • REST is good, SOAP is bad. Reese claims that
    SOAP is absurdly complex to implement and support when your target consumers use many different programming languages

    He further assers that

    JSON is good, XML is bad

    so REST - supporting JSON is better than SOAP enforcing XML - statement, that was directly debated by Gerald Loeffler’ recent comment on "Is REST Successful in the Enterprise?".

    ... without contrasting and comparing technologies on a purely technical basis we would lose the rigor that any technical domain requires... as people become immersed in one way of seeing the world (you might call it an ideology; such as WS-* or REST, or statically typed or dynamically typed) they inevitable come to see it as the truth - it becomes so obviously true. But it isn't: it's just one way of making sense and reasoning about what's out there (with particular characteristics and properties - which is why we (also) need the purely technical debates). Sadly, in software development, truth claims for one's own viewpoint often end in insults against the opponents: they "don't 'get it".

The bad (and ugly) practices identified by Reese include:

  • Throttling is a terrible thing to do.
    If you are going to use throttling... you need to implement some very intelligent throttling that can a) recognize legitimate traffic like testing and regular polling and b) minimize the negative impact of false positives. Avoid limits based on "wild ass guesses" and consult with customers who might be impacted.
  • Chatty APIs suck. A chatty API, as defined by Reese, is any API that requires consumer to do more than a single call to perform a single, common operation. The details of what constitutes chatty, of course, depend on what people might reasonably want to do with the API.
  • Returning HTML in response. Reese suggests that the response from a service should always be a valid JSON/XML even when it can't talk to the API server.
    If an API consumer EVER sees HTML, you are doing something very, very wrong.
  • Side-effects to 500 errors are evil. An API should always make sure that calls that generate 500 errors are idempotent - rollback any changes that might have occurred in the process of generating them.

Reese’s blog provides a set of very solid best practices on REST APIs implementation, describing not only Dos and Don’ts, but also Whys - the rationale behind some things being good or bad. These best practices are not REST specific - they do not talk about REST design or defining resources or choosing of proper parameters passing mechanism - they are good design practices for any API type.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

I think we live in a "post service" world by Jean-Jacques Dubray

1) first Web APIs is rapidly gaining traction, "Service" is the new "Distributed Object" (interesting to see API there though... :-)
2) Mobile apps are crying to be "Converged Applications", billions of converged apps are being sold every year.

There is probably a lot of definitions for Converged Apps, but for me it's an App that is bringing voice, messaging, data, video, sensors (remote or local) together (or a subset). A typical converged app would be for instance an app that is able to call FourSquare Web API to get my list of friends nearby, lookup their phone numbers from a "My Contacts" API (Local or Remote), then call Yelp to find the places where we could meet or EventFul for the events we could go to and finally call Twilio's SendSMS API, and see who responds.

Call that a Mashup or whatever, in any case, the "thing"** the view connects to is no longer a "service" or a "resource", worse, the "thing" that invokes these APIs has nothing to do with the owners of the APIs themselves and the resources that are managed via these APIs don't even belong to the Web API provider but the end user.

So we need a much more consumer centric "contract" than the "service centric" of the SOAP or REST days: the Mashup is the new "contract". At Canappi we call that a "connection", for better or worse. I have never been good at choosing name, but it goes well with "API". . Even the security mechanisms of this "thing" have changed, they need to be 3-legged to reflect the relationship resource/Enduser-converged application-Web API provider. OAuth is bringing that to the table, painfully.

So we can continue talking about these silly debates for another 10 years, the fact is that 99% of the Web APIs are not RESTful, OAuth needs more legs.., and Endusers are craving for buying Converged Apps (as in with real money, no longer "clicking") that need to be secure and respect their privacy. Nothing in WSDL or WADL prepared REST or SOAP for that world.

Debate is closed, let's move on. Converged Apps are a lot more fun that anything we have built so far.

** for those of you who missed it, MVC was originally called Thing-View-Controller pattern by T. Reenskaug.

Re: I think we live in a by Boris Lublinsky

The thing never was a service, it was always something that is using services. Call it mashup, composed or converged app or just "blah", at the end of the day it is a mini workflow, that knows where to get information, and how to massage it and present to the user. Services, on another hand are information providers and as such should provide interfaces = APIs, that the thing should invoke. The better these APIs are designed, the easier it is to implement the thing.
So, at the end of the day, APIs design matters a lot

Re: I think we live in a by Jean-Jacques Dubray

>> The thing never was a service
Well, it was a time, long ago when people talked about "contracts" between consumers and providers. My point was to say that these contracts are obsolete. Converged Apps are pushing the boundaries of what we once thought was a contract.

>> The better these APIs are designed
you are kidding? right? Do you see any effort whatsoever to "better design" these APIs? it is all over the place without any particular thought about where things should go (version, query parameters, verbs, HTTP headers, MAC signature). So APIs like put the APIKEY, Username, Password in every request path, as ... query parameters. Four square uses verbs in their REST APIs, Facebook uses FB identifiers in the request path, which comes really handy for marketers to keep track of the activities of all these globally and uniquely identifiable humans (GUIH).

I'd like to see proof of a "better" design.

Re: I think we live in a by Dilip Krishnan

IMHO, RESTfull services are very different from RESTfull API. The very fact that they are referred to as API's are a smell with respect to the architectural style. Smell because they bring an RPC feel to the style implicitly, which quite naturally warrants contracts/documentation and such, because the tooling around it demands them as such.

Even so, the fact that we're able to create consumers of the API, RESTfull or otherwise, compose these services into "converged apps" or mashups that use these services in ways that the creators of the service dint even dream of is where the power of the architectural style shines! The web as a platform serves as a canvas for these interesting compositions.

Re: I think we live in a by Jean-Jacques Dubray

>> where the power of the architectural style shines
I see the "shine" every day. It is so bright that I have to wear sun glasses to code.

The REST concept degraded. by William Martinez

I hear REST API, REST Web Service, REST connector, REST Workflow, REST Protocol (the worse), and even REST communication methodology or style. All these are misconceptions and are actually degrading the REST concept.

REST is a style. One that is based on the whole web needs. With strategic combination of guidelines to accomplish a particular set of needs in terms of quality properties.
- REST is not a API definition recipe.
- REST is not a web Services construction methodology
- REST is not a workflow engine.
- REST is not a communication style.
So, we cannot compare REST against RPC, makes no sense. We cannot compare REST against SOAP, it is plain impossible. We can talk of other ways of implementing things, that may use the REST restrictions that made it famous. But REST is an architectural style, and as such should be discussed. Examples?

REST as a lightweight web service. REST is about a networked application that is optimized for large grain hypermedia transfer, allowing high visibility, anarchic scalability at internet level, modifiability, discoverability and actually not processing intensive. It is about creating an application, not a service. It is not about processing, but about datum transfer and manipulation. It is specific about hypermedia, which is a special king of data that may have status and control information along with business one. A client for such a thing is a specialized component. So, no, that cannot be a lightweight thing.

So, please, REST is not about URL templating or about HTTP error codes. It is about quality properties and strategic design for very large things. When we understand that, we may be able to understand why the list in this article refers to an HTTP based API, not about REST.


William Martinez Pomares

"JSON is good, XML is bad" ? by Herman Bovens

I RTFA, but didn't see Reese's assertion that "JSON is good, XML is bad" at all.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

7 Discuss