- May 02, 2013

There is an ongoing debate to determine the best practices of API design. This is often related to the following terms:

Recently, I read “Getting hyper about hypermedia APIs“, a blog post from David H. Hansson (Rails’s creator). Looking at both the quality of his arguments and the defensiveness of the readers’ comments, he clearly hit a nerve.

To understand why this is important, let’s compare the REST and Web API design architecture styles in tension.

REST style, as defined by Roy T. Fielding

REST was formally defined in 2000 for systems that are both distributed and driven by hypermedia interactions with humans.

Fully embracing it requires you to respect the 5 mandatory constraints (plus an optional one), as described below.

Note that this summary contains large excerpts from Roy T. Fielding’s thesis:

1 – Client-Server constraint

  • separation of concerns
  • client = user interface concerns (
  • better UI portability across platforms)
  • server = data storage concerns (more
  • simple and scalable implementations)
  • independent evolution of clients and servers at Internet scale

2 – Stateless constraint

  • each client request must contain all the info necessary for the server to respond
  • session state is kept entirely on the client

3 – Cache constraint

  • allow client to reuse response data in a controlled manner
  • support intermediaries such as proxies and shared caches

4 – Uniform Interface constraint

  • central and unique feature of REST API design
  • less efficient than a customized interface due to the standardization overhead
  • efficient for large-grain hypermedia data transfers
  • not optimal for other forms of architectural interaction
  • sub-constraints
    • identification of resources via URIs
    • manipulation of resources through representations (HTML hyperlinks, forms or JavaScript/AJAX style)
    • self-descriptive messages
    • hypermedia as the engine of application state (HATEOAS)

5 – Layered System constraint

  • each component only knows about the immediate component/layer it is interacting with
  • favor intermediary components (load-balancers, reverse proxies, shared caches)
  • can add overhead and latency
  • gives pipe-and-filter benefits (combined with Uniform Interface constraint)

6 – Code on demand constraint [optional]

  • client component doesn’t know how to process the resources it has access to
  • code representing this know-how is retrieved by the client and executed locally
  • dynamic feature addition to deployed clients
  • improved extensibility and configurability
  • better user-perceived performance and flexibility
  • improved server scalability (offload work to the client)
  • lack of visibility requires client to trust the server (security sandboxing required)

In addition to these constraints, REST also defines as a set of architectural elements that directly abstract the semantics of the HTTP application protocol:

  • data elements
    • resource (conceptual target)
    • resource identifier (typically an URI)
    • representation (HTML document, bitmap image)
    • representation metadata (media type, modification date)
    • resource metadata (allowed methods, alternates)
    • control data (content negotiation, conditional requests, compression)
  • connectors (client, server, resolver, tunnel)
  • components (origin server, user agent, gateway, proxy)

Finally, REST defines three views that illustrates the style including the process, connector and data view. The last one illustrates what a REST client can be:

  • primarily an hypermedia browser, including ability to do incremental rendering
  • an automated robot performing information retrieval for an indexing service
  • a personal agent looking for data that matches certain criteria
  • a maintenance spider busy patrolling the information for broken references or modified content

End of excerpts.

The web of documents and browsers, as we know it, is the best example of the REST style in action. This is logical as REST was inferred from the earlier Web architecture during the specification of HTTP version 1.1.

However, looking at Roy T. Fielding recurrent reactions regarding the improper usage of “REST” as a buzzword, it is time to question whether the REST style can be or should be used when building regular Web APIs.

Web API style, as practiced today

Web APIs are designed for systems that are both distributed and driven by machine-to-machine interactions.

This Web API style is the result of the evolution of pragmatic development practices since 2000, starting with the emergence of Web Services (WS-* and *-RPC) and then the strong influence of the REST style towards more simplification and proper usage of HTTP as an application level protocol rather than a lower-level transport protocol.

Let’s attempt to formalize this style in a way similar to REST. Embracing it requires you to respect the 6 constraints described below:

1 – Client-Server constraint

  • separation of concerns
  • client = program with varying concerns (maximum reusability needs)
  • server = data or logic accessibility concerns (build ecosystems of innovation)
  • independent evolution of clients and servers at Application scale
  • significant difference from REST

2 – Stateless constraint

  • identical to REST

3 – Cache constraint

  • identical to REST

4 – Custom Interface constraint

  • predefined set of resources including identifiers and representations
    • cool URIs that don’t change
    • developers friendly URI naming based on conventions
  • more efficient than dynamic discovery
  • requires coordination between clients and servers when changes are deployed
    • based on explicit versioning
  • efficient for both small-grain mobile data transfers as well as large-grain data transfers
    • based on parameterized resources and content negotiation
  • not optimal for other forms of architectural interaction
  • sub-constraints
    • identification of resources via URIs (identical to REST)
    • manipulation of resources through low-level HTTP clients (using for example raw JSON or XML representations)
    • manipulation of resources through high-level client SDKs (for major programming environments) when available
    • developer documentation to help with understanding of the interface
  • significant difference from REST

5 – Layered System constraint

  • identical to REST

6 – Mobility constraint

  • intermittent Internet connectivity
    • potentially unavailable for a long time
    • requires an off-line application mode
  • expansive Internet connectivity
    • typical mobile data plans have data limits per months
    • ability to switch to less expansive radio networks when available
    • highly dependent on actual client location
  • irregular bandwidth (potentially very low)
    • adjust media size dynamically
  • irregular latency (potential very high)
    • aggressively use cache (by default)
    • synchronize cache when possible
  • not present in REST

As you can see the Web API design style has been very much influenced by REST and share many of its constraints. This influence over 10 years has resulted in key simplifications compared to the original RPC style to make it more aligned with the core Web concepts such as resources, URIs, representations and the HTTP protocol.

REST and Web API design styles are web brothers

There is no reason to oppose both styles as they are not solving the same problems, even though they are both deeply connected with the Web. The figure below represents their main differences.


Both styles are complementary and can be used together, for example when building a single page web application where the main HTML is loaded through a regular web page (REST style), including some JavaScript (code on demand constraint). This code is then interpreted by the web browser to make AJAX calls back to a Web API, exchanging predefined JSON representations.

Let’s also mention hyperdata as a second form of hypermedia with hypertext, that also offers a comprehensive application of REST. This is the world of the Semantic Web and especially the pragmatic Linked Data movement based on RDF and related media types such as Turtle, JSON-LD or HAL.

In other situations, where the client isn’t a web browser but a native mobile app, a connected device or a program written by a partner to integrate your web site with their own, you only rely on the Web API style, which is fine again. Let’s now step back and see where these new forms of web architectures will lead us.

Building cross-device web sites

By combining the power of REST (the web of documents) and of Web APIs (the programmable web), we can build a new generation of web sites that are inherently cross-device. as illustrated below.

Cross-device web sites

Those web sites let organizations of all sizes provide a pervasive and contextual access to their information and services, to both customers, employees and partners via potentially any kind of machine.

I will wrote more about cross-device web sites in future posts as they help understand the strategic value brought by Web APIs in this new era of mobility.


CTA_free trial_3

  • Pingback: “How much REST should your web API get?” by @j… –

  • This is a very interesting and well considered view of how to write a client in a client-server approach. It is very nice to see someone doing justice to Roy Fielding’s definition of REST.

    It is also nice to see a start in developing an architectural style for machine to machine interactions.

    The essential difference between the two seems to me to be whether a person is present in the interaction. When a person is present it is safe simply to render hypermedia as the person will be able to interpret that hypermedia semantically. In this case the client is acting as an agent for the person, as for example Outlook or Thunderbird act as agents for email (a different application). In addition, the client is loosely coupled to the server – we can extend the server or change the implementation without changing the client. This is what makes the Web work.

    When a person is not present, the client must know much more than just how to render the data received from the server. This requires a deterministic binding of the client to the server. This binding is usually compiled into the client. Attempts to soft code the semantic agreement have proved very hard to manage in a heterogeneous environment (cf JINI and CORBA for instance).

    The Internet of Things (IoT) cannot, it seems to me, depend on this kind of semantic tight coupling. We either need agreements on application protocols (like SMTP for email) or we need something like REST to make it scale.

  • @John Another use case to consider is when the person is present but doesn’t have or want access to a rich user interface supporting hypermedia. In this case, you can’t rely on REST either.

    I agree that this causes issues regarding the scalability of a world with only custom Web APIs. We need standard APIs, subject of another blog post planned 🙂

    • @Jerome Although this use case does exist (for instance, doing mobile banking using SMS) it is very niche compared to the requirement for “engaging applications whose state is shareable using links”. We write software for banks and this is what they want for their advisers in the branch and for their customers on mobile or Internet.

      • There is also the voice2text gateways. Also, how do you deal with partners or other departments requiring a remote/programmatic access to the application?

  • Interesting approach, and I do agree that pure REST is often not a best fit for web APIs.

    I would like to see more elaboration on the following, ideally with example of what the words actually mean:

    -client = program with varying concerns (maximum reusability needs)
    -server = data or logic accessibility concerns (build ecosystems of innovation)
    -independent evolution of clients and servers at Application scale

    Also I wonder if “Connectivity Constraint” would be better word choice than “Mobility constraint?”

  • @Mike For client / server : a Web API can potentially be invoked by HTML/AJAX code, a remote program runnng at a partner site, an iOS mobile app, an IFTTT rule, and so on. Open APIs are frequently used to build ecosystems of innovation where you don’t know in advance how the API and its underlying data could be used.

    For Independent evolution of client and servers at Application scale, it means that based on a given Application (versionned), the clients can be built and deployed without constraint from the server side (beyond authorization aspects). On the other hand, the server implementation could change independently as long as the web API definition/contract itself doesn’t change.

    Regarding the Mobility constraint, it expresses more than just the fact the the connectivity could be lost. It also expresses the fact that the geographic location of the client(s) could vary more or less rapidly and that the Web API architecture should still perform well.

  • Pingback: How much REST should your web API get? | Softwa...()

  • Pingback: Dew Drop – May 8, 2013 (#1,543) | Alvin Ashcraft's Morning Dew()

  • Pingback: New release of APISpark rolled out | Realize your Web APIs !()

  • Pingback: I’ll be moderating a discussion of @jlouvel’s… –

  • Aegean BM

    I wrote a SPA that uses ajax to shuttle JSON to/from a REST server I also wrote in Jersey. I love the total decoupling of client and server. Life is so much simpler. BUT …

    I had the REST server also serve the HTML files. I don’t like this approach because it re-couples them again. I was able to reduce the code smell to two REST urls.

    Any advice on how to do organize things if you have to both the browser client and the REST server?

  • Thanks for your comment, IMO, you shouldn’t distinguish the HTML files from the REST of your resources. They are implemented differently, but from a logical/conceptual point of view they are all resources identified by URIs and exposing representations (some in HTML, some in JSON).

    In term of server modularization, you could simply have two applications, on for the HTML pages bootstrapping and the other of the Web API backing it, especially if this API is reused by other types of clients.

  • Dan Wong

    Thoughtful article but I don’t agree with the way you try to distinquish the two style.

    Your main argument is that REST is for interaction with a browser while Web API can support system-to-system. But the fact is REST APIs can be consumed beyond browers. Machine to Machine communication is also supported. One REST API can be the consumer of another REST API (composition) via technology such as JAX-RS or ASP.NET.

    Because REST is a very loose standard (basically HTTP protocal), it resulted in various standards/conventions being specified by various providers. But the core principle/architecture style is very comparable. Hypermedia is a subset of REST and does not define REST. Many providers avoid the additional complexity of Hypermedia and leverage primarily the CRUD HTTP methods and that is a choice for the use case applied.

  • Thanks Dan for sharing your views. In the general “REST API” meaning you are correct. As the creator of the Restlet API ( I fully understand how “REST-inspired” web APIs can be valuable for machine consumption.

    Here I’m trying to be more precise, going back to the REST architecture style exactly as defined by Roy T. Fielding here:

    In his writings which are very precise, REST was designed exactly and explicitly for to purpose of powering hypermedia-driven web applications.

    The fact that many principles in REST are still relevant beyond hypermedia clients (or even at the same time) is important but creates confusion about what a “REST API” is or should be, hence this blog post.