--- marp: true paginate: true math: mathjax theme: buutti title: REST Architecture --- # REST Architecture ## 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 ## 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)