You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
160 lines
7.4 KiB
Markdown
160 lines
7.4 KiB
Markdown
---
|
|
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)
|