API Design: A New Model for Pragmatic REST

Brian Mulloy

Jul 04, 2013

In our last post, we talked about pure REST and HATEOAS. In this post, we'll propose some ideas to initiate the creation of a new API design model based on pragmatic REST. We need to create an intellectual framework for API design that captures the spirit of how most popular web APIs are designed today.

Let's start our discussion with a very specific question about including links in API responses.

If you aren’t going down the path of HATEOAS,should you include links in API responses?

If you think including links in API responses are helpful for developers at design time then, both a pragmatist and a hypermedia enthusiast would agree, go for it. Chances are, developers will exercise editorial control over responses but this (along with good API documentation) will go a long way toward guiding them. Ideally, it’s nice to have well-designed error messages so that developers can focus on test-driven development.

However, if you decide to include links in the API response for developers at design time, a REST purist wouldn’t call it HATEOAS because the links are probably not the engine of app state for the app user at runtime. You might also get a scolding from Roy Fielding on his blog.

“If the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?”~Roy Fielding, “REST APIs must be hypertext-driven”, Untangled: Musings of Roy T. Fielding

HATEOAS is fundamental to REST. If you aren’t HATEOAS compliant then you don’t have REST, and you are probably taking pragmatic shortcuts.

The API community has some agreement on what a compliant client looks like and what makes up a SOAP API, but we don’t have an intellectual framework for the way popular apps and web APIs work today.

We must look at the constraints of REST and keep in mind the way custom apps are built today, by multiple app developers, using multiple apps, and web APIs.

For example, when looking at the sixth constraint of REST, the optional Code-on-Demand, you quickly realize why it is optional. You can’t expect that an API response that includes code will get executed for two reasons: 1) It conflicts with the first constraint of REST, the client-server separation; and 2) Without knowing the kind of code a client is using, you can’t automate a script because it might not execute.

The diagram above defies pure hypermedia constraint systems; yet, it represents the way API crafters are using web APIs today. Let's create a foundation for this new pragmatic REST model so that we (the pragmatists) have something to refer to when we discuss API design. My only other request is that we choose a nice pronounceable acronym to go with it.

To join the conversation around APIs, check out the API Craft Google Group and the IRC Channel #api-craft on freenode.