Laytoun' thoughts!

No! HTTP APIs are not necessarily Rest APIs

Mohammed Aboullaite -

Lately, an interesting discussion triggered by Josh Long and Hadi Hariri‏ about, humm, many things honestly! But there is one tweet that is particularly worth to mention:

Well, Beside the fact that a REST API is not necessarily an HTTP API (since there are other transfer protocols available, yet they are less popular), I agree with what Josh and Hariri said and many people confuse the two since REST and HTTP seem to be hand-in-hand. After all, the world-wide-web itself runs on HTTP, and it makes sense, a RESTful API does the same. However, there is nothing in the REST constraints that makes the usage of HTTP as a transfer protocol mandatory. It's perfectly possible to use other transfer protocols like FTP, SMTP and others to use, and your API could still very well be a RESTful API.

REST is a design style for protocols, it was developed by Roy Fielding in his PhD dissertation and formalised the approach behind HTTP/1.0, finding what worked well with it, and then using this more structured understanding of it to influence the design of HTTP/1.1. So, while it was after-the-fact in a lot of ways, REST is the design style behind HTTP.

A RESTful system would obtain information about the resources concerned by GETting URI which would then return a document (e.g. in JSON, but not necessarily) which would describe the state of the resource, including URIs to related resources (hypermedia therefore), change their state through PUTting entities describing the new state or DELETEing them, and have other actions performed by POSTing.

Thus the following HTTP requests all have different meanings when using REST:

  • GET /api/customers
  • POST /api/customers
  • PUT /api/customers

There are only a few HTTP request methods. The full list is CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, and TRACE. You may be forgiven if you’ve never heard of a few of these, as some are almost never supported by client or server software.

Roy also advocated that HTTP response codes he helped define be used to communicate the meaning of the response. There are ~38 HTTP response codes. Below is a complete list:

Designing RESTful application is usually a lot harder because it requires you to describe complicated things in a simple manner. describing all functionalities using only CRUD functions is tricky, but after doing that your life would be a lot simpler and you will find that you will write a lot shorter methods.

The classic example of a non-RESTful system using HTTP is something which treats HTTP as if it was a transport protocol, and with every request sends a POST of data to the same URI which is then acted upon in an RPC-like manner, possibly with the connection itself having shared state.

Let's consider the following example:

Request
GET api/customers/10
Response
            {
           "customer":{
              "id":"10",
              "name": "customer name",
              "age": "28"
           }
        }

While such APIs have borrowed some of the REST principles, such as identifying each resource by an ID, accessing resources via hyperlinks, providing multiple representations for resources (JSON, XML) – they do not abide to all REST principles, applying the so called “pragmatic REST”, resulting in multiple interpretations of REST. Fielding expressed his frustration with “RESTful” API implementations years ago, informing API designers that several rules need to be followed for an API to be called RESTful.

Long story short, there is a big difference between a RESTful API and a HTTP API. A RESTful API adheres ALL the REST constraints set out in its "format" documentation (in the dissertation of Roy Fielding). A HTTP API is ANY API that makes use of HTTP as their transfer protocol. This means that even SOAP can be considered a HTTP API, as long as it will use HTTP for transport, but most HTTP APIs will make more and better use of the infrastructure and possibilities of HTTP. Most HTTP APIs can be very close to becoming a truly RESTful API. This can be defined by their Richardsons maturity level.