CMPUT 404

Web Applications and Architecture

REST

Created by
Abram Hindle (abram.hindle@ualberta.ca)
and Hazel Campbell (hazel.campbell@ualberta.ca).
Copyright 2014-2023.

REpresentational State Transfer

  • Representational
    • Describe, name, show
  • State
    • The current values of variables, properties, fields
    • Accumulation of the results of past changes
  • Transfer
    • Sent from computer to computer, or from service to service
    • Communication

REST

  • Architectural style
    • Think design patterns for a software system architecture
  • Introduced by Fielding's Dissertation
  • Now so common, it's usually just implied and not discussed explicitly

REST Architecture

  • Client/Server
  • Stateless
    • The server does not need to track the state of the client
  • Cacheable
  • Uniform interface
  • Layered

REST Basics

  • Use URIs (URLs) to "name" objects
    • Java/JS/Python/database objects!
  • Use HTTP methods as verbs to manipulate them
    • GET - get the state of an object
    • PUT - set the (entire) state of an object
    • PUT - create an object
    • DELETE - delete an object
    • POST - manipulate an object some other way

REST is not RPC

  • RPC - Remote Procedure Calls
  • Call a procedure (function/method) over the network
  • Same semantics as calling a function!
    • Inputs
    • Outputs
  • But, that function runs on a different computer.
  • Rest thinks about objects not functions

REST is not RPC

  • Stateless
  • Client maintains its own state
  • Server does not track clients at all
  • Requests are big
    • Lots of context
    • All the fields/properties
      • Maybe recursively!
    • Client must send all relevant state

REST is not RPC

  • Stateless
  • Server maintains only state relevant to core DATA MODEL objects
  • Client maintains state like
    • Position in a sequence (UI flow)
    • Logged in & identity

REST is not RPC

  • Uses a generic interface with standard semantics: HTTP
  • GET always gets the state of an object
  • PUT always sets the state of an object
    • Create it if it doesn't exist

REST is not RPC

  • Transformable: You can stick proxies in between the client/server
    • Caches
    • Load balancers
    • Failover
    • ...

Caching REST

  • Client can cache responses
  • Can also insert a caching reverse proxy
  • If the entity doesn't change, why request it again?
  • What methods are cacheable?
    • GET? Yes!
    • POST? No :(

Layering REST

Layering REST

  • Your application may not be multi-machine
  • But it can still have layering that uses HTTP
  • Example: Separate layer that just handles and validates authentication, before passing it off to the next layer
  • Example: Stateless routing some requests to a different process (db1, db2)

Types of requests

  • Repeatable - doing it twice in a row is same as doing it once
    • Idempotent
  • Stateless - the request/response itself contains all necessary state information
  • Cacheable - the results are the same for some period of time
  • Safe - doesn't cause any change

HTTP Methods in REST

GET PUT DELETE POST
Repeatable Yes Yes Yes Maybe
Stateless Yes Yes Yes Maybe
Cacheable Yes Yes Yes No
Safe Yes No No No

Example: Search Query

  • Is it Repeatable?
  • Is it Stateless?
  • Is it Cacheable?
  • Is it Safe?

Example: Check the weather

  • Is it Repeatable?
  • Is it Stateless?
  • Is it Cacheable?
  • Is it Safe?

Example: Add a photo to gallery

  • Is it Repeatable?
  • Is it Stateless?
  • Is it Cacheable?
  • Is it Safe?

Example: Make a payment to a shop

  • Is it Repeatable?
  • Is it Stateless?
  • Is it Cacheable?
  • Is it Safe?

Session Cookie Authentication: is it REST?

Signed Token Authentication: is it REST?

Why REST?

  • Reliability
  • Scalability
  • Latencies
  • Efficiency
  • Distributed

REST Reliability

  • Allow more than 1 machine to handle the same task
    • If 1 machine dies, we can send requests to another
  • Server doesn't have to track client state
    • Can't get out of sync

REST Scalability

  • Sharding
    • Split data across multiple machines
    • More capacity + more performance

REST Latency

  • Caching decreases latency
    • Every layer can have caching
  • Multiple layers increases latency

REST Efficiency

  • Higher bandwidth
    • Every request needs contain all relevant state & context

REST Distributed

  • Separate concerns -> separate servers
    • "Microservices"
  • State distributed between server and client

Designing REST

  • What is read-only vs read-write
  • What is public vs needs to be authenticated
  • What relationships can become URIs?

Designing REST

  • Take advantage of caching
    • Prefer GET & Avoid POST
  • Can a single object be split up into separate objects with separate URLs?
  • Can something be stored client-side instead of on the server?
    • Remember: the client side is the fastest side!

Use nouns for paths, not verbs!

  • getRecipeInstructions() → GET api/v1/recipes/1234

Plural nouns for paths if its a Collection

  • Arrays/Lists/Vectors
  • Mappings/Dictionaries
  • Sets
  • getAllRecipes() → GET api/v1/recipes/

Sub-directories (sub-folders) for hierarchies

  • api/v1/recipes/1243/versions/2

Use HTTP error codes

Use HTTP error codes

  • GET → 200 OK
  • New object via PUT or POST → 201 Created
  • DELETE → 204 No Content
  • Needs authentication → 401 Unauthorized
  • Bad JSON or missing/extra properties or bad value → 400 Bad Request
  • POST to an endpoint that only understands GET & PUT → 405 Method Not Allowed

HATEOAS

  • Hypermedia As The Engine of Application State
  • Include hyperlinks in your REST API responses!
GET api/v1/recipes/1243/versions/2
{
    "ingredients": [
        {
            "name": "Flour",
            "link": "/api/v1/ingredients/27"
        },
        ...
    ],
    ...
}

More REST tips

More REST tips

License

Copyright 2014-2023 ⓒ Abram Hindle

Copyright 2019-2023 ⓒ Hazel Victoria Campbell and contributors

Creative Commons Licence
The textual components and original images of this slide deck are placed under the Creative Commons is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Other images used under fair use and copyright their copyright holders.

License


Copyright (C) 2019-2023 Hazel Victoria Campbell
Copyright (C) 2014-2023 Abram Hindle and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN.

01234567890123456789012345678901234567890123456789012345678901234567890123456789