REST Concepts

What is REST?

  • Equating JSON+HTTP/1.1 with REST is inaccurate. REST itself does not define a communication model, but rather how web services can be designed for distributing hypermedia in a scalable fashion.

  • REST insists on uniform interfaces. HTTP has become the de facto standard for creating uniform REST APIs.

RESTful Architectures

Reference: RESTful Web APIs by Leonard Richardson, Mike Amundsen and Sam Ruby. Published by O’Reilly on 12 Sep 2013.

  • Representation State Transfer (REST) or RESTful architectures are design to manage change in APIs. Its about naming resources with URLs and how to properly use HTTP methods. Its also about Hypermedia, the feature that makes a web API capable of handling changes gracefully.

  • REST makes use of the fact that, web servers do not know anything about the client browser’s HTTP session and the client has no direct control over the server’s resource state. This is in contrast to something like the FTP protocol with long lived session between the client and server. HTTP requests on the other hand are short lived TCP connections. Send a request and get an answer.

  • REST is a set of design constraints around statelessness and hypermedia, using the three technologies: URL, HTTP and HTML. The hypermedia is the resource which can be any tangible item that is useful, such as an electronic document, a row in a database or the result of an function. The only restriction is that every resource must have a URL.

  • The whole idea behind RESTful APIs is to allow software to “surf” an API similar to how humans would surf the world-wide web, by discovering http links from the root web page (or resource) and traversing the links in the root as necessary to get other relevant resource for the software.

The Collection Pattern

 1{
 2  "collection": {
 3    "version": "1.0",
 4    "href": "http://www.thomas-pk.com/api/",
 5    "items": [
 6      {
 7        "href": "http://www.thomas-pk.com/api/613856331910938",
 8        "data": [
 9          {
10            "name": "text",
11            "value": "Squidly!"
12          },
13          {
14            "name": "date_posted",
15            "value": "2013-03-28T21:51:08.406Z"
16          }
17        ]
18      },
19      {
20        "href": "http://www.thomas-pk.com/api/18645119667053223",
21        "data": [
22          {
23            "name": "text",
24            "value": "rjogil"
25          },
26          {
27            "name": "date_posted",
28            "value": "2020-06-09T02:40:26.116Z"
29          }
30        ]
31      }
32    ],
33    "template": {
34      "data": [
35        {
36          "prompt": "Text of message",
37          "name": "text",
38          "value": ""
39        }
40      ]
41    }
42  }
43}

The example JSON provided above could be from the http request “http://www.thomas-pk.com/api/”.

  • Collection href (line 4): Provides a permanent link to the collection

  • Item attribute href (line 7): A link to the standalone resource item outside the context of its collection.

  • items (line 5): Provides members of the collection

  • template (line 33): Hypermedia control for adding a new item to the collection

 1{
 2  "collection": {
 3    "version": "1.0",
 4    "href": "http://www.thomas-pk.com/api/",
 5    "items": [
 6      {
 7        "href": "http://www.thomas-pk.com/api/613856331910938",
 8        "data": [
 9          {
10            "name": "text",
11            "value": "Squidly!"
12          },
13          {
14            "name": "date_posted",
15            "value": "2013-03-28T21:51:08.406Z"
16          }
17        ]
18      }
19    ],
20    "template": {
21      "data": [
22        {
23          "prompt": "Text of message",
24          "name": "text",
25          "value": ""
26        }
27      ]
28    }
29  }
30}

Given above is the body of a http request “http://www.thomas-pk.com/api/613856331910938” for a single item from the previous collections request.