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:


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.


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 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


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": "",
... etc


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


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 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 a representation of a resource
Destroy a resource
Create a new resource underneath this one, based on the given representation
Replace the state of this resource with the given representation

The next two are mainly for exploring and API

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

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

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


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.


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.


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


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.