---
marp: true
paginate: true
math: mathjax
theme: buutti
title: REST Architecture
---

# REST Architecture

<!-- headingDivider: 5 -->
<!-- class: invert -->

## REST - What it actually is?

* Style of software architecture commonly used to create networked services
* REST comes from "representational state transfer"
* Defined by Roy Fielding in 2000 as architecture for distributed hypermedia systems.  Incidentally, NOT made for web services at all
* Developed in parallel with HTTP1.1
* While (almost) any application layer protocol can be used, REST APIs are almost always built on HTTP

## REST architecture

* Data and functionality are resources
* Resources are accessed through URIs
* Resources are acted upon by simple and well-defined operations
* Clients and servers exchange representations of resources using a standardised protocol (usually HTTP)
* Resources are decoupled from representations
  * Allows content to be accessed in a variety of formats (e.g. HTML, XML, plain text, image formats, JSON, etc.)
  * Resource metadata is available to be used for detecting errors, negotiate the appropriate representation format, access control, control caching, etc.
* All resources are stateless

<!-- Access control: e.g. key token validation
Statelessness: 
every response is isolated; fulfilling requests is not dependent on any other requests
client is responsible for sending the data about itself -->

## REST requirements

* For something to be considered RESTful, it needs to follow a set of architectural constraints
  * Be client-server
  * Client context must not be stored on server (server is stateless)
  * Explicitly reusable responses (cacheable)
  * Have an uniform interface, with the restrictions
  * Be designed to be a layered system (you don't need to know if you are targeting the end server directly, or something in-between)

## REST constraints 

### REST constraints - Client-Server

* First constraint is client-server
  * Separation of concerns
    * Separate user interaction from data
    * Allows independent evolvement of components; no need to rebuild server if UI needs a rework, and vice versa
  * Scalability by simplification of server components
  * Portability of the user interface across platforms

### REST constraints - Statelessness

* Servers must be stateless
  * Intended to improve visibility, reliability and scalability
  * Each request from the client must contain all the necessary information to understand the request
  * Requests cannot take advantage of stored context on the server
    * This means that in true RESTful services session state is stored entirely on client side
  * Single request can be used to determine full nature of the request
  * No need to manage resource usage across requests
    * Server can quickly free resources for other requests
  * Easily recover from partial errors

### REST constraints - Cacheability

* Client-cache-stateless-server
  * Statelessness enables some endpoints to always produce the same result with the same request
  * Responses to requests can then be explicitly marked as cacheable
    * Clients can reuse cached responses for the same requests
    * Reduces repetitive requests
  * Potential to eliminate some interactions completely
  * Trades reliability for performance, efficiency and scalability
    * What happens when the data updates?
  * At this point, we are at design rationale for the early (pre-1994) world wide web architecture

### REST constraints - Uniform interface

* Central distinguishing feature of REST style
  * REST implementations are restricted by four interface constraints
    * identification of resources
    * manipulation of resources through representations
    * self-descriptive messages
    * hypermedia as the engine of application state
  * Transfer information in standardised form rather than specific to application's needs
  * Implementations are decoupled from the services they provide
    * Encourage independent evolvement at the cost of efficiency

### REST constraints - Layered system

* Allow architecture to be composed of hierarchical layers
  * Last required constraint
  * Let components "see" only the immediate layer they are interacting with
    * Arbitrary amount of servers accessible by this layer
  * Reduce overall system complexity by restricting knowledge of the system to a single layer
    * Encapsulate legacy services
    * Protect new services from legacy clients
    * Hence bugs and errors in old code cannot be exploited, while still preserving functionality
  * Enable load balancing
  * Tradeoff here is added overhead and latency

### REST constraints - Code-on-demand

* Optional final constraint
  * Client functionality is allowed to be extended by downloading and executing code in the form of applications or scripts
    * Goal is to simplify clients by reducing amount of pre-implemented features
    * Is optional in REST because of reduced visibility
    * Can be a problem from security viewpoint

## REST elements

### REST elements - Resources

* Basic REST abstraction is a  _resource_
  * Any information that can be named
    * Document, news article, image, collection, person, etc.
  * Identified with a  _resource identifier_
    * Commonly URI
    * Identifies resources interacting between components
  * State of a resource at a certain timestamp is called a  _resource representation_

### REST elements - Representation

* Consist of data, metadata describing it and hypermedia links
  * Hypermedia links help clients to transition to the next desired state
    * This is where the name Representational State Transfer comes from
    * Hypermedia means just that the controls are presented with the information, the links on web pages being the obvious example
  * The data format of a representation is called a  _media type_ .  The media type identifies how a representation should be processed by the client
* Self-descriptive
  * Client does not need to know if the resource is a book or an employee, it should act according to the media type associated with the resource
    * Often leads to creating a lot of custom media types

## RESTful APIs

* Note that most "REST API"s out there do not fill these requirements
* Often any web API on top of HTTP is incorrectly described as "RESTful"
* Most commonly hypermedia isn't used as the engine of application state, or the application is not really stateless, and some people outright ignore those requirements from the get-go
  * (which in case of both, technically makes the system RPC, not REST, but the name still sticks)

## Yet more REST ramblings

* A REST API should be entered without prior knowledge beyond the initial URI and the appropriate media types
  * i.e. media types expected to be understood by all clients that might use the API
* Moving forward, application state transitions are driven by client selection from server-provided choices present in the received representations
  * This is to keep interaction driven by in-band information
* REST does not equal HTTP
  * As long as the REST constraints are honoured, the interface can be called RESTful

## Reading

* [Fielding's paper](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) is available online and is relatively short
* https://restfulapi.net/ seems like a good resource
* Wikipedia is plain wrong, but less wrong in English than in Finnish \[citation needed\]
* [Roy T. Fielding: REST APIs must be hypertext-driven](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven)
