REST API Guide

REST is the most popular method for building modern internet APIs. Every time you use a modern web or mobile app or visit a website, you're probably using a REST API. For software developers, knowing how to use and build such APIs is essential. But what is REST, and how does it work?

In this in-depth guide, we'll provide you with a solid foundation and practical knowledge about REST and building RESTful APIs.

What is an API?

Before diving into REST, let's briefly explain what API means. API, or Application Programming Interface, is a way for two programs to speak with each other. The programs can be on the same phone, computer, or on different continents. Although there are many different kinds of APIs, in this guide, we're focusing on online APIs.

Online, or web, APIs, allow applications and servers to communicate over the Internet. For example, the Twitter app on your phone uses an API to connect to Twitter's servers to send and receive updates.

Well written APIs are fast, stable, secure, easy to use, and well documented. Through the evolution of the internet and the web, developers invented various API architectures. Today, the most popular way to design an online API is by following REST principles.

What is REST API?

REST stands for Representational State Transfer. It is a way of organizing online APIs powering most of the modern web. It was first described in a 2000 doctoral dissertation, which defined REST as a style of designing network-based software architectures conforming to several guiding principles.

REST concepts

The core concepts (or constraints) in REST are:

  • Client-server architecture. The client (for example, a web browser) handles the user interface, and the server (for example, a web server) takes care of data. This separation of concerns allows for independent development of client and servers.
  • Stateless communication. The client communicates with the server by issuing requests (for example, "get a web page") to which the server responds ("here's the web page"). Each request is independent of, and can be processed separately from, other requests. This allows multiple servers to share the work, and keeps the clients and servers simple.
  • Uniform interface. A way of accessing data that works the same way for all clients and servers. This means that a client doesn't need to be written specially for each server. Instead, a single client (such as a web browser) can be used to access many different servers, and a single server can serve many different clients (web browsers, mobile apps, etc).
  • Cache. Server responses can be marked as cacheable, so the client doesn't need to re-request data it already has. This speeds up communication over slow internet links.
  • Layered system. Additional layers or components can be added to communication, without changing the clients or the servers. For example, the servers may be behind a load balancer that equally divides the work between multiple servers, without the client knowing about it.
  • Code on Demand. The client can optionally be extended by downloading a script from the server. The script provides additional functionality specific to that server. In most modern web apps, the browser downloads and executes JavaScript code as needed. This extending through on-demand JavaScript code is what makes the browsers the most popular application platform today.

Uniform interface

Uniform interface is achieved by following another set of constraints:

  • Identification of resources. Each resource (or a piece of data) on the server must be uniquely identified. The client uses this unique resource identifier, officially called URI (Uniform Resource Identifier), to ask the server for the data. In practice, the term URL (Uniform Resource Locator) is more widespread and means the same thing. The URL uniquely identifies every page on the internet. If you type it in your browser, it will know how to access it, no matter which server hosts it.
  • Resource representations and Descriptive messages. Each resource has a defined representation (file format). The resource data is accompanied by metadata (data about the data) in each request and response, telling the server or the client all the information needed to use or modify a resource. For example, when the client requests a web page, the server's response will include information that the page is in HTML format. If the client requests an image, the server include metadata specifying the image's format to be PNG or JPEG.
  • Hypermedia as the engine of application state (HATEOAS). The client should not need prior knowledge of how the resources are organized on the server. All information, such as related links or possible actions on a resource, should be listed in the resource itself. In practice, modern APIs rarely conform to this constraint. This means creating a truly unversal REST API client is not possible, and the developers of an API client need to know the details of how the API in question works.

What is a RESTful API?

An API that conforms to the constraints specified in the definition of REST is called a RESTful API. In practice, not all RESTful API follow the definition to the letter. Most most APIs ignore or half-implement the HATEOAS constraint. Web apps often have a concept of a "user session", keeping information about the user on the server and explictly violating the stateless communication principle.

Still, most RESTful APIs work in similar manner. Aside from following the REST constraints, the term often implies a few other aspects of the API:

  • HTTP(S). Although REST doesn't imply using HTTP as the underlying protocol, virtually all RESTful APIs are built on top of it
  • JSON or XML. Most modern APIs use the JSON file format for resource representation. Some use XML, or allow the client to choose between both.

The term is also useful to distinguish RESTful APIs from other popular architectural styles:

  • SOAP (Simple Object Access Protocol). In contrast to REST, which is an architectural pattern, SOAP is a protocol with precise specification. SOAP uses XML as the data format and is built on top of HTTP. The servers must describe the data objects and allowed methods in detail using Web Services Definition Language (WSDL), which is also based on XML. SOAP is less widely used than REST, but is still sometimes used in governmental and big corporation systems.
  • RPC (Remote Procedure Call). A style of APIs where the server defines procedures (code) that the client can invoke. Where in REST the client would use a method on a resource, in RPC the client would ask the server to do something (call a procedure). In practice, many RESTful APIs have some RPC functionality because it is hard to implement all of the client-server communication in purely REST style.
  • GraphQL (Graph Query Language). GraphQL is a protocol aiming to address some performance shortcomings of REST. It treats all the resources on the server as nodes in a graph, linked by their relationships to each other. For example a "Book" object in would be linked to an "Author" object. GraphQL provides a means of requesting and modifying multiple nodes in that graph at once. It is a somewhat new protocol but is gaining in popularity.

Is there a difference between a REST API and RESTful API? Not really. The terms are mostly synonymous and refer to the same thing. Sometimes people use REST API for APIs that fully conform to the definition of REST, and RESTful API for APIs that loosely follow it, but in most cases, they can be used interchangibly.

REST vs HTTP

HTTP (HyperText Transfer Protocol) is an internet protocol for client-server communication that powers the web. Every time you're visiting a web page, you're using HTTP. Your browser asks for a web page by issuing a HTTP request, and the server responds by returning the HTTP response.

Although REST, in its definition, is not directly tied to HTTP, RESTful APIs in practice always use HTTP as the underlying protocol implementation.

REST, as an architectural style, grew out of experiences with early HTTP. In turn, REST influenced the development of the protocol, and later versions of HTTP include some features that are directly inspired by REST.

Although we're talking about HTTP, modern web sites and APIs in practice use its secure, encrypted version, HTTPS. HTTPS is normal HTTP, just encrypted so that nobody can snoop in, or alter the communication between the client and the server.

REST vs CRUD

CRUD refers to Create, Read, Update and Delete, the most basic operations for accessing and manipulating data. It is a way of describing how data access works in databases, user interfaces, and APIs.

In RESTful APIs, CRUD describes the operations that can be done on resources, and maps to HTTP request methods:

  • Create (HTTP POST) - create a resource on the server
  • Read (HTTP GET) - read a resource, or a collection of resources, from the server
  • Update (HTTP PUT and HTTP PATCH) - update a resource on the server
  • Delete (HTTP DELETE) - delete a resource from the server

Some API operations can't be neatly mapped to CRUD. For example, following a user on Twitter is an action, not a resource. For such operations, RESTful APIs use RPC-style communication, where the client asks the server to do something outside CRUD. This is usually done using HTTP POST method.

Example of a RESTful API

In this imaginary example, a public library has an API that lets users browse and reserve books. We're ignoring security to keep things simple: in reality, users would first need to log in, and only the admins would have the permission to add, modify or delete books and authors.

The API will allow CRUD operations on the books, and an additional RPC-style method to make or cancel a reservation for a book.

The API would expose (or offer to the client) the following endpoints (resource URLs):

  • GET example.com/api/books/ - List all books in the library
  • GET example.com/api/books/<book-id> - Get information about the book with ID <book-id>
  • POST example.com/api/books/<book-id>/reserve - Make a reservation for a book with the ID <book-id>
  • POST example.com/api/books/<book-id>/cancel - Cancel a reservation for a book with the ID <book-id>

Library administrators would also have access to endpoints used to manage books:

  • POST example.com/api/books/ - Add a book
  • PATCH example.com/api/books/<book-id> - Update information for a book with the ID <book-id>
  • DELETE example.com/api/book/<book-id> - Remove a book

To create a book, the client sends a HTTP POST request to example.com/api/book with the resource data in JSON format and metadata in request headers:

{
    "id": "978-1-56619-909-4",
    "title": "The Lord of the Rings",
    "author": "J. R. R. Tolkien",
    "year": 1955
}

The server creates a book and responds to the client with the 200 OK response, again returning the newly-created book data in JSON format.