webdev-basics/rest-architecture.md

marp	paginate	math	theme	title
true	true	mathjax	buutti	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 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