REST APIs

What are REST APIs?

API-First Software relies on REST APIs to efficiently distribute data & services across the internet

Why REST matters for web APIs?

Billions of people use the web in one form or another. Millions of developers create web applications. Yet only a small number of them have heard about REST, which defines the architectural style of the web. REST was created by Roy T. Fielding, the primary architect of HTTP 1.1, the backbone protocol of the web.

REST is the acronym for REpresentational State Transfer. It’s a set of principles that, when correctly applied, helps in building software architectures and applications that benefit from all the qualities of the web. Those qualities are numerous and include greater scalability, efficient network use, and independent evolution of clients and servers (also called loose coupling).

Now, would you build a Gothic church or an art deco hotel without knowing about the Gothic or art deco architectural styles? Certainly not! The same is true for the web; you shouldn’t build web applications without knowing about the architectural style of the web. By understanding the principles defined by REST and applying them in your development, you’ll be able to create web APIs with highly valuable properties such as scalability, loose coupling, performance, and simplicity.

REST APIs are made of Resources and Representations

Fielding describes software architectures as a configuration of architectural elements, which are, in the case of REST, components, connectors, resources, representations, and a few data elements. In the following sections we take a look at the higher-level architectural elements, because this provides a good way to start comprehending REST.

Let’s start our exploration with the most important element: resources. They’re the building blocks of web APIs. A resource can be anything of interest that an application wants to expose on the network for other applications to use. It can be the balance of a bank account, the current temperature in Paris, a Shakespearean text, a video of a play, a collection of pictures, a blog post, and so on.

One important characteristic of those resources is that they’re linked together by embedded hyperlinks in HTML documents or URI references in feeds pointing to recent blog posts. In exactly the way it was envisioned and named by its creator Tim Berners-Lee, the web is a distributed set of resources that can be navigated and discovered dynamically.

What’s amazing is that all those resources—retrieved, updated, or deleted by users, humans, or robots—form a complex system that’s constantly evolving and growing. The figure below illustrates this and shows the potential relationships between resources via hyperlinks. In practice, only a few relationships will be used and may sometimes even be broken. We all know the 404 “Not found” error pages that are annoying but that also prove the liveliness of the web.

To allow users to retrieve them from anywhere in the world, each resource is given a unique name called a Uniform Resource Identifier or URI (for example, http://www.paris.fr/weather), enabling identification and remote access on the internet.

As shown in figure below, a resource can expose its state via representations containing both metadata (such as size, media type, or character set) and content (binary image or text document). The representation of a confirmation of purchase on eBay could be an HTML document; for a wedding picture it could be a JPEG binary stream; for a contact in an address book web service it could be an XML fragment; and so on.

Let’s look closely at a resource to see how it’s typically implemented in an information system. The circle in figure below delimits the resource from its external environment, which interacts with it.

The resource is composed of some state depicted at the center, managed in any way that makes sense (like in a database, in a file, or computed dynamically) and of standard methods (like GET, PUT, DELETE, or POST explained right after) that together define its uniform interface.

To give you an idea of the importance of resources, you can compare them to objects in the object-oriented paradigm. They are the backbone of your web applications, exposing both state and behavior. Compared to the object-oriented paradigm, the standard resource methods (usually HTTP methods) are similar to object methods, with a key difference: they’re limited in number and have a behavior that’s predefined by a protocol such as HTTP. Because applications use predefined methods, instead of defining their own, to express interactions over the network, the network infrastructure can understand to a certain degree the semantics of the interactions it’s carrying on. From this understanding comes the ability to provide a number of key services such as caching and automatic message reemission, things an infrastructure can’t do blindly without understanding some of the application-level semantics of the interactions.

REST APIs

Now that we introduced the disruptive nature of REST, we hope you better understand how REST asks you to rethink software development in the web age. REST requires you to think in resources instead of the objects of the object-oriented world or the tables of the relational world. Those resources are identified by URIs and hyperlinked together, exposing representations of their state. They also offer a uniform way to interact with them, mainly via the HTTP standard methods (GET, PUT, DELETE, POST, and so on).

Providing a REST API while providing useful capabilities to its consumers isn’t trivial. It requires special skills to understand the problem domain, analyze the requirements, and design the set of resources composing the API. Figure above illustrates how we define a REST API as a set of hyperlinked resources, forming a subset of the web, exposed by a web service, web sites, microservices and so on.

At Restlet, we provide a REST Platform that helps DevOps teams quickly deliver microservices and more easily succeed in their API-First projects. You can learn more about each of these use cases below.

  • API-First

    API-First

    API-First software combines the best of REST APIs, microservices and DevOps to continuously deliver innovation

    Learn more
  • Microservices

    Microservices

    Digital transformation often lead to break software monoliths into microservices exposed as REST APIs

    Learn more
  • DevOps

    DevOps

    Continuously delivering microservices requires agile teams able to blend development, QA and technical operations

    Learn more