The Richardson maturity model

Level 1:

Resources

const countries = [
 { name: 'Norway', capital: 'Oslo' },
 { name: 'Denmark', capital: 'Copenhagen' },
];

// read a resource with HTTP GET
app.get('/countries', (req, res) => {
 res.send(counties);
});

// read a specific country
app.get('/countries/:name', (req, res) => {
 const name = req.params.name;
 return res.send(countries.find(
  c => c.name === name
 ));
});

// delete a country
app.get('/countries/:name/delete', (req, res) => {
 const name = req.params.name;
 const index = countries.findIndex(
  c => c.name === name
 );

 // remove the country
 countries.splice(index, 1);
 
 res.send(countries);
});

Level 2:

verbs

const countries = [
 { name: 'Norway', capital: 'Oslo' },
 { name: 'Denmark', capital: 'Copenhagen' },
];

// read a resource with HTTP GET
app.get('/countries', (req, res) => {
 res.send(counties);
});

// read a specific country
app.get('/countries/:name', (req, res) => {
 const name = req.params.name;
 return res.send(countries.find(
  c => c.name === name
 ));
});

// delete a country
app.delete('/countries/:name', (req, res) => {
 const name = req.params.name;
 const index = countries.findIndex(
  c => c.name === name
 );

 // remove the country
 countries.splice(index, 1);
 
 res.send(countries);
});

// old:
app.get('/countries/:name/delete', (req, res) => {

HTTP supports verbs

• GET: Read (Safe: NO side effects)
   
• HEAD: Only headers (Safe)
   
• POST: Create (saves a new instance)
   
• DELETE: Delete (removes an instance)
   
• PUT: Update (mutates an instance)
   
• OPTIONS: List of available verbs

Verbs + URL

• GET (no payload)
  • /cars
  • /cars/:identifier
     
• POST /cars
  • { "color": "red", "licence": "AB7839" }
     
• DELETE: /cars/:identifier
  • No payload
     
• PUT: /cars/:identifier
  • { "color": "green" }

Level 3: Hypermedia

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. – Roy Fielding

Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types. — Roy Fielding (in a comment)

Level 3 requirements

• A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API).
   
• A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server).
   
• A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.

Rich Apocada on StackOverflow, interpreting Roy Fielding

LEvel 3: HATEOAS

Hypermedia As The Engine Of Application State

class Customer {
  constructor(name) {
    this.name = name;
  }
}

// JSON representation
{ 
  "name" : "Alice"
}

// HATEOAS JSON representation
{
  "name": "Alice",
  "links": [ {
    "rel": "self",
    "href": "http://localhost:8080/customer/1"
  } ]
}

• rel means relationship. For example, an order might have a "rel":"customer" relationship, linking the order to its customer.
   
• href is a complete URL that uniquely defines the resource.

{
  "content": [ {
    "price": 499.00,
    "description": "Apple tablet device",
    "name": "iPad",
    "links": [ {
      "rel": "self",
      "href": "http://localhost:8080/product/1"
    } ],
    "attributes": {
      "connector": "socket"
    }
  }, {
    "price": 49.00,
    "description": "Dock for iPhone/iPad",
    "name": "Dock",
    "links": [ {
      "rel": "self",
      "href": "http://localhost:8080/product/3"
    } ],
    "attributes": {
      "connector": "plug"
    }
  } ],
  "links": [ {
    "rel": "product.search",
    "href": "http://localhost:8080/product/search"
  } ]
}   

More sophisticated

https

http://www.javacodegeeks.com/2013/04/understanding-transport-layer-security-secure-socket-layer.html

NO TLS

WITH TLS

let's encrypt