REST Introduction & HTTP (Media Engineering Web-Oriented Architecture)

# REST Introduction & HTTP

Learn the core architectural principles of REST and how they can be applied to
make RESTful web APIs with HTTP and URLs.

**You will need**

* [Google Chrome][chrome] (recommended, any browser with developer tools will do)
* [Postman][postman]

---
## What is a Web Service?

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a>]

**Clients** need access to **data** and **logic**.
How can they find each other, know what logic can be invoked, and talk to each other over the web?

---
class: center, middle
## Big web services

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a>]

---
### Remote procedure call (RPC) or remote method invocation (RMI)

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#3">Big web services</a>]

---
### Web services standards

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#3">Big web services</a>]

---
### Pros & cons

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#3">Big web services</a>]

Many standards:

* Simple Object Access Protocol (SOAP)
* Web Services Description Language (WSDL)

.grid-50[

**Benefits:**

* Very rich protocol stack:
  * support for security
  * transactions
  * reliable transfer

]
.grid-50[

**Problems:**

* Very rich protocol stack:
  * complexity
  * verbosity
  * incompatibility issues
  * theoretical human readability

]
---
class: center, middle
## REST

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a>]

*A cat RESTing...*

---
### What is REST?

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#7">REST</a>]

REST means [REpresentational State Transfer][rest]. It is an architectural style
for building distributed [web services][web-service] on the Internet. The World
Wide Web is one example that exhibits the characteristics of a REST
architecture.

> REST has been introduced in [Roy Fielding’s Ph.D. thesis][roy-fielding-thesis]
> (Roy Fielding has been a contributor to the HTTP specification, and to the
> Apache server and community).

An API or web service that follows REST's architectural constraints is said to
be a *RESTful API* or *RESTful web service*.

---
#### REST architectural constraints

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#7">REST</a> > <a href="#8">What is REST?</a>]

A system is considered to follow the REST architecture if it follows [these
constraints][rest-constraints]:

* **Client-server architecture:** the separation of concerns between the user
  interface (client) and data storage (server) improves portability across
  platforms, and allows components to evolve independently.
* **Statelessness:** each request from any client contains all the information
  necessary to service the request, and the session state is held in the client.
* **Cacheability:** clients and intermediaries can cache responses indicated as
  cacheable by the server, improving scalability and performance.
* **Layered system:** a client cannot ordinarily tell whether it is connected
  directly to the end server, or to an intermediary along the way. This improves
  scalability by enabling load balancing and shared caches.
* **Uniform interface:** a uniform interface simplifies and decouples the
  architecture, which enables each part to evolve independently.

---
#### So... what is REST?

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#7">REST</a> > <a href="#8">What is REST?</a>]

These are the basic principles of REST when applied to HTTP web services:

* The state of the application is captured in a set of **resources**
  * Users, photos, comments, tags, albums, etc.
* There is a **uniform interface** (**HTTP**) to manipulate those resources:
  * Resources are identified with a standard format (**URLs**).
  * Every resource can have several **representations** (e.g. HTML or JSON).
  * The client progresses through the application by applying operations (**HTTP
    methods:** GET, POST, etc) to resources and exchanging their representations
    with the server (**state transfer**).
  * The client can follow server-provided **hyperlinks** to discover available
    actions and resources ([HATEOAS][hateoas]).

> Note that REST does not mandate the use of HTTP and URLs, but it is the
> simplest and most popular way of implementing a RESTful web service.

---
### What is a web resource?

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#7">REST</a>]

Something that can be uniquely identified on the web:

.grid-50[

**Static content**

* An article published in the "24 heures" newspaper
* A person's birth certificate

]
.grid-50[

**Dynamic content**

* The collection of articles published in the sport section of the newspaper
* The list of grades of the student Jean Dupont

]
.container[

.grid-50[

**Intangible things**

* The current price of the Nestlé stock quote

]
.grid-50[

**Physical objects**

* The vending machine in the school hallway

]

]
---
### [Uniform Resource Locator (URL)][url]

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#7">REST</a>]

> "A reference to a **web resource** that specifies its **location** on a computer network and a **mechanism** for retrieving it."

* http://www.24heures.ch/vaud/2008/08/04/trente-etudiants-manifestent
* http://imdb.com/movies/best?page=3&pageSize=50&orderBy=title
* http://www.smart-machines.ch/customers/heig/machines/8272#order

The syntax of an URL is:

```
scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
```

---
### Resource vs. representation

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#7">REST</a>]

* In a REST API, we use the HTTP protocol to support the exchange of data (or **state transfer**) between a **client** and a **server**
* What is exchanged is not the actual resource: it is a **representation** of the resource
* The **same resource** could have:
  * An HTML representation
  * An XML representation
  * A PNG representation
  * A WAV representation

---
class: center, middle
## HyperText Transfer Protocol (HTTP)

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a>]

> "An [application protocol][osi-application] for distributed, collaborative,
> and [hypermedia][hypermedia] information systems. [HTTP][http] is the
> foundation of data communication for the World Wide Web."

---
### Evolution of HTTP

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a>]

* [HTTP/1.0][http] (1996) - [RFC 1945][http10-rfc]
* HTTP/1.1 (1999) - [RFC 2616][http11-rfc]
* [HTTP/2.0][http2] (2015) - [RFC 7540][http2-rfc]

> HTTP/2 is a more efficient expression of HTTP's semantics "on the wire",
  > which **maintains high-level compatibility with HTTP/1.1** (for example with
  > methods, status codes, URIs, and most header fields). It is now supported by
  > virtually all web browsers and major web servers.
* [HTTP/3.0][http3] (2022) - [RFC 9144][http3-rfc]

> HTTP/3 is the proposed successor to HTTP/2, which is already in use on the
  > web, using [UDP][udp] instead of [TCP][tcp] for the underlying transport
  > protocol. **Like HTTP/2, it does not obsolete previous major versions of the
  > protocol.** Support for HTTP/3 was added to Cloudflare and Google Chrome in
  > September 2019, and can be enabled in the stable versions of Chrome and
  > Firefox.

---
### HTTP is a request-response protocol

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a>]

When you visit the following page:

```
https://en.wikipedia.org/wiki/Film
```

Your browser makes an HTTP **request** and gets a **response**:

```http
GET /wiki/Film HTTP/1.1
Accept: text/html,*/*
Host: en.wikipedia.org
```

```http
HTTP/1.1 200 OK
Content-Length: 58330
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
 <head>
 <meta charset="UTF-8"/>
 <title>Film - Wikipedia</title>
 </head>
 <body>
 ...
 </body>
</html>
```

---
### Anatomy of an HTTP request

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a>]

Get the third page of a movies list:

```http
GET /movies/best?page=3&pageSize=50&orderBy=title HTTP/1.1
Accept: text/html,*/*
Host: www.example.com
```

```http
POST /api/movies HTTP/1.1
Content-Type: application/json
Host: www.example.com

{
  "name": "The Matrix",
  "releaseYear": 1999
}
```

---
#### Request method

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#17">Anatomy of an HTTP request</a>]

The first line of an HTTP request is the **request line**:

```
  `GET` /movies/best?page=3&pageSize=50&orderBy=title HTTP/1.1
```

The **request method** is the *desired action* to perform:

There are [more methods][http-methods].

---
#### Resource path

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#17">Anatomy of an HTTP request</a>]

The second part of the request line is the **resource path**:

```
  GET `/movies/best`?page=3&pageSize=50&orderBy=title HTTP/1.1
```

It tells the server where to find the resource to perform the action on.

---
#### Query string

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#17">Anatomy of an HTTP request</a>]

The **query string** is the third part of the request line:

```
  GET /movies/best`?page=3&pageSize=50&orderBy=title` HTTP/1.1
```

These are parameters given to the server, usually to *filter* the resource.
In this case:

* `page=3` - we want the third page
* `pageSize=50` - we want pages of 50 movies
* `orderBy=title` - we want the movies ordered by title

---
#### Headers

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#17">Anatomy of an HTTP request</a>]

After the request line, an HTTP request has one or more **headers**:

```http
GET /movies/best?page=3&pageSize=50&orderBy=title HTTP/1.1
*Accept: application/html,*/*
*Host: www.example.com
```

This allows the client to tell the server how to serve the request:

* `Accept: application/html,*/*` - I prefer HTML, but otherwise give me any format you have
* `Host: www.example.com` - This is the domain I want the resource from

There are many [headers][headers] that can be used in requests.

---
#### Request body

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#17">Anatomy of an HTTP request</a>]

The **body** is data that the client can ask the server to do something with:

```http
POST /api/movies HTTP/1.1
Content-Type: application/json
Host: www.example.com

*{
*  "name": "The Matrix",
*  "releaseYear": 1999
*}
```

In this case:

* It's a `POST` request, so the server should create a new resource
* The `Content-Type` header is `application/json`, so the server should
  interepret the body as a JSON payload and use that data to create the resource

---
### Anatomy of an HTTP response

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a>]

An HTML page:

```http
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
 <head><title>Film - Wikipedia</title></head>
 <body>...</body>
</html>
```

A resource we just created:

```http
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/api/movies/xo349

{
  "id": "xo349",
  "createdAt": "2017-02-08T11:05:40+01:00",
  "name": "The Matrix",
  "releaseYear": 1999
}
```

---
#### Status code and reason phrase

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#23">Anatomy of an HTTP response</a>]

The first line of an HTTP response is the **status line**:

```
  HTTP/1.1 `201 Created`
```

The **status code** and the **reason phrase** indicate to the client whether the request was successful and how to handle it:

| Code | Reason               | Purpose                                                                                                                                 |
| :--- | :---                 | :---                                                                                                                                    |
| 200  | OK                   | The response body contains the requested resource.                                                                                      |
| 201  | Created              | The `Location` header contains the URL of the created resource; the response body may contain a representation of the created resource. |
| 401  | Unauthorized         | Authentication is required and was not provided or is invalid.                                                                          |
| 422  | Unprocessable Entity | The request body is semantically invalid.                                                                                               |

There are many [status codes][http-status-codes] a server can use to help the client handle responses.

---
#### Headers

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#23">Anatomy of an HTTP response</a>]

Like requests, an HTTP response has one or more **headers** after the status line:

```http
HTTP/1.1 200 OK
*Content-Language: en
*Content-Type: application/json
*Last-Modified: Tue, 07 Feb 2017 02:12:22 GMT

{
  "id": "xo349",
  "name": "The Matrix",
  "releaseYear": 1999
}
```

It allows the server to give the client additional metadata about the response:

* `Content-Language: en` - The response contains information in English
* `Content-Type: application/json` - The response body is a JSON payload
* `Last-Modified: Tue, 07 Feb 2017 02:12:22 GMT` - The resource was last modified on February 7th

There are many [headers][headers] that can be used in responses.

---
#### Response body

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a> > <a href="#23">Anatomy of an HTTP response</a>]

The response body is the (optional) data sent by the server.
Its nature depends on what the request was and what the response status code indicates.
It could be the requested resource for a `GET` request:

```http
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json

*{
*  "id": "xo349",
*  "name": "The Matrix",
*  "releaseYear": 1999
*}
```

Or it could be a list of errors if the body of a `POST` request was invalid:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

*[
*  { "field": "name", "message": "Name is required" },
*  { "field": "releaseYear", "message": "Release year must be >= 1890" }
*]
```

---
### HTTP provides the [content negotiation][http-content-negotiation] mechanisms

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a> > <a href="#14">HyperText Transfer Protocol (HTTP)</a>]

Different **representations** of a resource can be exchanged at the **same URL**:

.grid-50[

A JSON representation:

```http
GET /shows/game-of-thrones HTTP/1.1
*Accept: application/json
```

```http
HTTP/1.1 200 OK
*Content-Type: application/json

{
  "title": "Game of Thrones",
  "releaseYear": 2011,
  "seasons": 6,
  "episodes": 60
}
```

]
.grid-50[

An HTML representation:

```http
GET /shows/game-of-thrones HTTP/1.1
*Accept: text/html,*/*
```

```http
HTTP/1.1 200 OK
*Content-Type: text/html

<html>
 <head>
 <title>Game of Thrones</title>
 </head>
 <body>
 <h1>Game of Thrones</h1>
 A 2011 TV show.
 <ul>
 <li>6 seasons</li>
 <li>60 episodes</li>
 </ul>
 </body>
</html>
```

]
---
class: center, middle
## But can't I just use GET and POST?

.breadcrumbs[<a href="#1">REST Introduction & HTTP</a>]

I'm lazy that way.

---
### Standards