HTTP and RESTful APIs

RESTful APIs treat resources as entities and HTTP requests can return responses about the state of those resources at any given time.

HTTP (and subsequently REST) requests are stateless. That is, an HTTP server does not maintain or care what state the client is in.

HTTP relies on IP (Internet Protocol) whose individual packets/frames are 14600 bytes each.

HTTP offers us verbs that can tell the server how the client wants to interact with the resource. There are 8 verbs:

GET | HEAD | DELETE | POST | PUT | OPTIONS | PATCH

LINK | UNLINK – draft methods

CONNECT | TRACE – used in proxies

The page you load up is known as the (web) “application state“.

The resources behind a particular URL are managed via the web application interface for that particular resource. The state of the resources is known as the “resource state“.

We make the distinction between app and resource state as we don’t want to confuse the two if we can avoid it.

HATEOAS

Hypermedia As The Engine Of A Service.

Each response should tell us how to get to the next response… this is also known as connectedness.

GET

GET requests are requests for a representation of the state of a resource. i.e. GET requests do not change any resource state(s) on the server. GET is therefore considered a safe method since you won’t delete all the data or anything like that with it.

Each HTTP response is split into 3 parts:

  1. Response code
  2. Body
  3. Headers

JSON

We use JavaScript Object Notation (JSON) to pass objects around as a list of key value pairs written as a tree structure. Json should be served as application/json and nothing else otherwise we may conflict with the JSON RFC

{
  "key1": "value"
  "list1": [ 1, 2, 3 ]
  "tree": {
     "a": 1,
     "b": 2,
     "c": [ {}, {}, {} ],
  },
  "href": "http://www.example.com/api/someresource",
... etc
}

Collection+JSON

Collection+JSON values must have a key: “collection”

The Mime-type is: application/vnd.collection+json

Collection+JSON is a way of serving lists specifically, not lists of data structures.

{ "collection": {...} }

There are other rules to follow for a list to be a valid Collection+JSON object.

Each object inside the collection items list must have its own href property and each value of href is a valid URL/resource

JSON vs HTTP

When an Http server returns you have no way of knowing if the response is the string “9” or the integer value 9. With JSON this confusion is not present since we transmit 9 when we mean integer, and “9” when we mean string value.

REST

REST is not a protocol or RFC. Its a set of constraints on how we build APIs/Web applications. It is a design process that follows constraints in Roy T. Fielding’s (2000) Ph.D dissertation. This paper and an article (titled: The world wide web, Volume One) explain the decisions behind the design of the Web and the three technologies that came out of those decisions: HTTP, URL and HTML.

When a server receives a request to create a resource, its job is to create that resource or reject the request. The client specifies what they want the resource to look like. The server may then add to the client’s representation, or alter it, or ignore parts of it.

When a POST | PUT | PATCH request is made, the server’s job is to make/update a resource to look like the client request. This is representational state transfer.

Sometimes a server has many different representations for the same resource. The primary/standard one is the “canonical” representation. The resource could be displayed in different languages/representations (Json/XML) and we have to negotiate which one to return, typically using different URLs for each representation.

HTTP Protocol Semantics

In a RESTful system there are rules. Clients and servers communicate via HTTP using the HTTP verbs

GET
Get a representation of a resource
DELETE
Destroy a resource
POST
Create a new resource underneath this one, based on the given representation
PUT
Replace the state of this resource with the given representation

The next two are mainly for exploring and API

HEAD
Get headers that would be sent along with a representation of this resource but not the representation (body) itself
OPTIONS
Discover which HTTP methods this resource responds to

PATCH
Modify part of the state of this resource based on the given representation

LINK
Connect some other resource to this one
UNLINK
Destroy the connection between some other resource and this one

GET

Sending a GET request has the same effect as not sending a GET request. i.e. no effect. Its purely for retrieving data and should have no effect at all on the state of a resource. Logging/Rate limiting are ok but a client should never make a GET request hoping that it will change a resources state.

DELETE

Sent when a client wants to destroy a resource so that it cannot be referred to again. If a DELETE request succeeds, they may return a 204 No Content | 200 OK | 202 Accepted (I’ll delete it later). Attempting to GET a resource may result in a 404 Not Found or 410 Gone. DELETE is not a safe method.

Idempotence

DELETE is not a safe method, and so very different from not sending a DELETE request. Another property it has is that its idempotent.

If we DELETE a resource, subsequent DELETE requests may respond differently but the resource state is exactly as it was after the first request. The resource is still gone. That’s idempotence. Sending the request twice has the same effect as sending it once.

Idempotence is a useful feature since the Internet is not a reliable network. If a request times out with no response, we can simply send it again and nothing additional will happen second time around. This notion comes from maths… multiplying a number by 0 (DELETE) results in 0 no matter how many times you do it. Multiplying by 1 (GET) is a safe operation and returns the same result all day long, and nothing will change that result.

Every safe operation is idempotent

POST-to-append

The post method has 2 jobs.

  1. create a new resource under the URL creates a resource from the request body received by the server.

POST’s common response is 201 Created (with location header set to the new location of the resource), 202 Accepted – so the server intends to create the resource but its not necessarily created yet.

Difference between URI and URL

The main difference between a URI and URL is that a URI has no protocol attached. Eg. an ISBN number for a book, whilst the URI will pin point a specific book by its book identification number, a URL will also specify a protocol for communicating about a given resource.