Comments on “The Good, the Bad, and the Ugly of REST APIs”

A survivor of intimate contact with many Cloud APIs, George Reese shared his thoughts about the experience in a blog post titled “The Good, the Bad, and the Ugly of REST APIs“.

Here are the highlights of his verdict, with some comments.

“Supporting both JSON and XML [is good]”

I disagree: Two versions of a protocol is one too many (the post behind this link doesn’t specifically discuss the JSON/XML dichotomy but its logic applies to that situation, as Tim Bray pointed out in a comment).

“REST is good, SOAP is bad”

Not necessarily true for all integration projects, but in the context of Cloud APIs, I agree. As long as it’s “pragmatic REST”, not the kind that involves silly contortions to please the REST police.

“Meaningful error messages help a lot”

True and yet rarely done properly.

“Providing solid API documentation reduces my need for your help”

Goes without saying (for a good laugh, check out the commenter on George’s blog entry who wrote that “if you document an API, you API immediately ceases to have anything to do with REST” which I want to believe was meant as a joke but appears written in earnest).

“Map your API model to the way your data is consumed, not your data/object model”

Very important. This is a core part of Humble Architecture.

“Using OAuth authentication doesn’t map well for system-to-system interaction”

Agreed.

“Throttling is a terrible thing to do”

I don’t agree with that sweeping statement, but when George expands on this thought what he really seems to mean is more along the lines of “if you’re going to throttle, do it smartly and responsibly”, which I can’t disagree with.

“And while we’re at it, chatty APIs suck”

Yes. And one of the main causes of API chattiness is fear of angering the REST gods by violating the sacred ritual. Either ignore that fear or, if you can’t, hire an expensive REST consultant to rationalize a less-chatty design with some media-type black magic and REST-bless it.

Finally George ends by listing three “ugly” aspects of bad APIs (“returning HTML in your response body”, “failing to realize that a 4xx error means I messed up and a 5xx means you messed up” and “side-effects to 500 errors are evil”) which I agree on but I see those as a continuation of the earlier point about paying attention to the error messages you return (because that’s what the developers who invoke your API will be staring at most of the time, even if they represents only 0.01% of the messages you return).

What’s most interesting is what’s NOT in George’s list. No nit-picking about REST purity. That tells you something about what matters to implementers.

If I haven’t yet exhausted my quota of self-referential links, you can read REST in practice for IT and Cloud management for more on the topic.

7 Comments

Filed under API, Cloud Computing, Everything, Implementation, Manageability, Mgmt integration, Modeling, Protocols, REST, SOAP, Specs, Tech

7 Responses to Comments on “The Good, the Bad, and the Ugly of REST APIs”

  1. Stu

    I’ve sort of half given up on REST advocacy because it’s pretty impossible these days. People want to ship APIs that will be valid for the next next 6 months, not build systems that will evolve over a decade or more.

    Jan Algermissen’s comment about how when you’ve documented an API, you’re not really doing REST, is actually spot on, fundamentally, but is met with ridicule by both you and George. I can completely understand how vacuous the comment sounds if you just want to ship an API nownownow, are being short-term practically minded, or are just playing buzzword bingo with architectural styles. But if we actually want to leverage the benefits of the style, we’d work on the core issue of having a generic media type or two for these sorts of use cases.

    If one is thinking of “how to methods map to my URI structures”, we’ve basically lost the plot as to why we have HTTP, URIs and media types in the first place. The goal is to *eliminate* the API as we normally think of it.

  2. Stu,

    I admit I don’t get what you mean by “we’d work on the core issue of having a generic media type or two for these sorts of use cases”. Well, I think I get it, but the way I understand it it doesn’t in any way remove the need for documenting the semantics of your interface so I guess I don’t get it.

    WRT to long-term planning, I hear you about how rigor pays off in the long term, but I would also guess that the #1 predictor of whether an API will still be used 10 years down the road is whether it actually built a significant usage mass in its first 6 months…

  3. Stu

    My point is threefold. The consequences of REST changes some rules:

    1. The assumption can’t be that the end user of your information service is going to be a programmer. Building an API bakes that assumption in how you expose your information or controls to manipulate it. The assumption rather should be that “this can be any agent of any sort”. If your goal really is “I want a programmer to learn my API and program against this”, then there’s really no reason to use REST other than that it’s trendy.

    2. The assumption can’t be that you will be the only site implementing your interface. The whole point of the Web is sharing information – publishing an API bakes in the assumption that YOU, the publisher, are in control. It is the consumer, on the other hand – the agent itself, that’s in control of how/what the information is consumed or manipulated.

    3. The semantics of the interface that need to be documented are the media type that you use to describe your data and links. The structure of your URIs really shouldn’t be a part of said semantics.

    4. But doing this in a custom media type implies #2, that you’re the only person implementing your interface. Of course, every media type has to start somewhere, but it really doesn’t help matters unless you understand that others may be *implementing* your interface, not just *talking* to it. Facebook’s Open Graph, for example, is an example of a custom overlay media type that takes great pains to be generic in either direction.

    5. All of the above is really heady stuff that is above most developer’s pay grades, so it won’t ever happen. The best we can hope for is some person/organization to step up with a generic media type or two + guidelines that help describe and document a Web of Data interface for accessibility by programmers. Call it a description language, if you’d like. Some RESTians don’t like the idea of a description language. I think it’s an essential 80/20 piece if developers are going to actually *use* the architecture the way it was meant to be used.

    Currently (as I mentioned in my WS-REST keynote) I think some kind of hierarchical lifecycle/state machine might be the right abstraction for such an interface. I’d like to demonstrate this if I ever got past my day job sucking up most of my time.

  4. Stu

    Apparenlty I can’t count. That’s five-fold ;)

  5. JJ

    >>The goal is to *eliminate* the API as we normally think of it.
    There has never been any evidence of that, except for the most trivial resources. I would argue that when you consider the resource lifecycle, the “API” will always be there. You are trying to pretend that “gravity” doesn’t exist because somewhere, under certain conditions (a parabolic descent) someone has experienced no gravity.

    I am glad the industry has recovered its senses from this REST nonsense. When the lifecycle of a resource matches the one of a document you can be restful. Otherwise, you are simply hancoding an action protocol.

  6. Stu

    Let me clarify – I meant Network APIs. I.e. Exposing an API across a network. APIs in general won’t go away.

    That said, if you consider a resource exposing a lifecycle, that could be seen as an API. But if we’re interacting using the vernacular of statecharts — signals, events, conditions, transitions, etc. That’s a very different programming model than just a flat API.

  7. Pingback: Understanding the Good in “The Good, the Bad and the Ugly of REST APIs” « The "Present" I live in