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

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