A guide to restful APIS

What is a REST API?

Nov 4, 2020

If you’ve ever tried working with data online, chances are you’ve noticed the transactional nature of the internet. You click a link, watch a video, publish a Tweet, and in the background a range of systems communicate in milliseconds. If you’ve looked into how these systems interact, you would have heard of the term API, and more specifically, REST API.  But what makes an API RESTful? 

An API is an application programming interface which allows programs to communicate with each other. APIs are usually hosted on a server which allows multiple clients to interact with them. Clients could take the form of separate systems or individual machines. In order to communicate effectively, programs need to speak the same language: shared languages allow for this transfer of information.

REST can be thought of as a set of rules for how this communication takes place. At a basic level, REST is a call and response model for APIs.

Initially defined by Dr Roy Fielding in 2000, Rest API stands for Representational State Transfer. REST API relies on HTTP to transfer information using requests, called ‘URLs’, to return specified data, called ‘resources’, to the client. Resources can take many formats such as images, text, video, amongst other formats. 

A request consists of four elements:

  • The endpoint,
  • The method,
  • The headers, and: 
  • The data (also called ‘the body’).

Endpoints can be either fixed or dynamic, depending on the URL called. For example, a URL could link to a list of names, or it could link to one specific name, using its unique identifier. 

The method refers to the kind of action a request can take. These request methods align with Create, Read, Update, and Delete actions of CRUD applications. The primary HTTP methods used with endpoints are: 

  • GET: This reads or retrieves data such as a list of names, a specific video, or an image, for example. 
  • POST: This creates new data, such as adding a name to a list. 
  • PUT/PATCH: This creates new data or updates existing data. To use this method, you must provide all the necessary fields for the resource.
  • DELETE: This removes data. 

The request headers can be thought of as the external wrapping of the request. Headers contain information about the content of the request, and are read by both the client and server.

The data, or body, of a request contains the information you send to the server. This element of a request is used with POST, PUT, PATCH and DELETE requests, but not with GET requests. 

There are six principles which make an API RESTful:

  • Client-Server separation
  • Statelessness
  • Cacheable
  • Uniform interface
  • Layered system; and
  • Code on demand (optional)

Client-Server separation

By disarticulating the client interface from the server implementation, the transfer of information becomes much more scalable, flexible and portable. With REST API, as long as the endpoints and returned data format remain the same, the client-side code can be updated, rewritten or evolved as needed without affecting the server. In the same way, improvements are made on the server without affecting the client’s interactions. This client-server separation allows systems to upgrade and adapt independently while retaining their ability to communicate.

client server REST API


This refers to the server not retaining any information about who uses the API, or what it was used for. Every request to the server contains all information needed to parse the request and return the response. The request therefore does not, and cannot, rely on any context stored on the server. During the communication, the server does not store the state; the state is maintained on the client side. Each request can be thought of as self-contained. 

stateless REST API


This principle requires data to be implicitly or explicitly noted as cacheable or non-cacheable. Cacheable responses allow the client to reuse the response data for later, comparable requests. The advantage of cacheable data is that it reduces the amount of bandwidth required to parse the request. In some cases, cacheable content could remove the need for a client to interact with a server, leading to more efficient communication. 

Cacheable content comes with a caveat: it could negatively impact on the reliability of a system by increasing complexity due to caching mechanisms, and by compromising data integrity due to expired or outdated content. 

Uniform interface

This principle of RESTful architecture relies on the linked concepts of generality and anticipation. Because it is impossible to build the precise interface required for a multitude of diverse clients, building a generic interface leads to higher visibility of interactions which allows the API to satisfy the requirements of multiple clients. However, the drawback of this generic, uniform interface is that it entails simplification, which therefore leads to a lower grade interface for many clients. 

Layered system

This principle is linked to the client-server separation discussed earlier. By constructing hierarchical layers in the architecture of the interface, components are restricted to interacting with a specific layer. They are unable to ‘see’ beyond this layer, and thus prevent the client from assuming any dependencies on the server-side. This modularity allows for the system architecture to be scaled and evolved without affecting the interaction between the client and server. 

Code on demand

Optional for RESTful APIs, this principle allows for functionality to be enhanced by executing snippets of code in the form of scripts. The advantage of this is that the number of pre-implemented features are reduced, resulting in simplified interactions. How this is implemented is that when a client makes a request for a resource, it receives both the resource (data) and the code to execute against that resource. The client knows only how to execute the code, not the construction of it.

When implemented in building APIs, these principles create an efficient, scalable way to provide users access to the multitude of decentralized cloud services available today. As these web services evolve, RESTful APIs can be upgraded to include the latest security and functionality without interrupting the client-server communication. With the myriad of RESTful tools available, REST APIs offer a simple but powerful way to leverage web services in your business processes. 

Consider low-code

APIs and microservices are fantastic if you’re a technical developer, but what if you’re not and you still need to understand how they connect?  A low code approach to building APIs offer a way to simplify complex application development and data integration into graphical, declarative configuration.  So whilst many will still use their preferred language and framework,  low-code accelerates the development lifecycle, making developers more efficient and productive. This provides an opportunity to accelerate the delivery of key initiatives without sacrificing quality.