REST APIs Introduction (Media Engineering Web Dev)

# REST APIs Introduction

Learn the core architectural principles of RESTful APIs are and how they compare to big web services.

This material is part of [web development courses](https://github.com/MediaComem/comem-webdev) for [Media Engineering](https://heig-vd.ch/formations/bachelor/filieres/ingenierie-des-medias).

**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 APIs Introduction</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 APIs Introduction</a>]

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

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

---
### Web services standards

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

---
### Pros & cons

.breadcrumbs[<a href="#1">REST APIs Introduction</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
## RESTful web services

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

---
### What is a REST API?

.breadcrumbs[<a href="#1">REST APIs Introduction</a> > <a href="#7">RESTful web services</a>]

* API means [Application Programming Interface][api]

> A clearly defined method of communication to interact with your program/service.

* REST means [REpresentational State Transfer][rest]

> An architectural style for building distributed computer systems on the Internet (i.e. it's a type of [Web Service][web-service]).

> 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 has been a contributor to the HTTP specification, to the apache server, to the apache community).

---
### Principles of a REST architecture

.breadcrumbs[<a href="#1">REST APIs Introduction</a> > <a href="#7">RESTful web services</a>]

* The state of the application is captured in a set of **resources**
  * Users, photos, comments, tags, albums, etc.
* Resources are identified with a standard format (e.g. **URLs**)
* Every resource can have several **representations**
* There is one unique interface for interacting with resources: **HTTP**

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

.breadcrumbs[<a href="#1">REST APIs Introduction</a> > <a href="#7">RESTful web services</a>]

Something that can be uniquely identified on the web:

.grid-50[

**Static files**

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

]
.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 APIs Introduction</a> > <a href="#7">RESTful web services</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 APIs Introduction</a> > <a href="#7">RESTful web services</a>]

* In REST, we use the HTTP protocol to support the exchange of data 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)][http]

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

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

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

.breadcrumbs[<a href="#1">REST APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#15">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#15">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#15">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#15">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#15">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][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>
 ...
</html>
```

A resource we just created:

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#21">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#21">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][http]</a> > <a href="#21">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 APIs Introduction</a> > <a href="#13">[HyperText Transfer Protocol (HTTP)][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 APIs Introduction</a>]

I'm lazy that way.

---
### Standards