API vs. REST vs. RPC vs. HTTP vs. JSON over HTTP vs. OpenAPI vs. Swagger

elevysi · 21 August 2021 |

once described how I embarked on an implementation of the Oauth protocol while referring to it as an authentication instead of an authorization protocol. Well, I may have found myself yet again in a similar situation and it seems to happen a lot. I tend to rush into adopting others’ solutions without having a full conceptual grasp and understanding of them. I usually get away with it through a technically working solution.

This time, the confusion is even broader as it addresses a common confusion that is often overlooked by a lot of people. A few weeks ago, if you would have asked me what REST stood for, I would have answered by contrasting it against SOAP. I would have probably attempted to explain that REST has to be stateless and that it revolves around the simple process of a client requesting a resource to a server and the latter replying with a JSON response (well, when I was getting acquainted with REST through CakePHP, I found out that REST could deliver any desired file format); nevertheless, I would have emphasized that JSON is the most common response format associated with REST while SOAP is often associated with XML. I would have argued that SOAP is more binding as it makes a remote procedure call (RPC) with some complex logic that is beyond my understanding and that REST is the norm nowadays and would have therefore advised focusing on REST.
Well, it turns out that my description fits more the HTTP protocol rather than REST. As a matter of fact, when I show off by saying that REST is stateless (all required information is contained within the request itself), so is HTTP; basically, what I have been calling REST is just JSON over HTTP.

API

A client, usually decoupled from the server, would make its requests to the server through the server's API (Application Programming Interface).  The latter is hence a third-party oriented system that aims at decoupling the services consumed by the server iteself and those consumed by other systems that are theoretically designed to be independent from the server. It is to contrast with other types of interfaces such as the user interface (UI) which is oriented towards the people rather than other computer systems. These systems will be the application's resources consumers; they can either be external consumers or internal building blocks of a large system (the same way a firm can use its staff for internal work and provide them for external consulting, an API can be consumed internally or externally - provided that the internal use case relates to a different decoupled computer system). For a web application, the access and manipulation of the server's resources is made through the HTTP protocol.

HTTP

HTTP stands for HyperText Transfer Protocol; it is a set of rules regulating how resources are transfered from a server to a client on the web. The web (or World Wide Web - WWW) denominates the system which enables the exchange of resources (identified by Uniform Resource Locators: URLs) from a server to the client using HTTP on the internet (the network that connects computers all over the world).
Some key concepts for the HTTP protocol on the client side are:

  • The URL / URI : this is what distinguishes resources from each other; the client should be aware of the URI of the resources it is interested in ( the URI - Unifrom Resource Identifier - identifies a resource and an URL includes, on top of the URI, information on how to access the resource such as the protocol to use (http, ftp,...): /api/notes/{noteID} would be the URI while https://notebyelvis.com/api/notes/{noteID} would be the URL)
  • Headers: this is the place to put metadata such as the authorization information, the wished data response format and so on.
  • The HTTP Verb : this comes in to supplement the URI; the client needs to tell its intention to the server with actions such as read, write, update or delete. For this, the protocol foresees a set of verbs to be used:
    • GET: usually associated with read operations
    • POST: for write operations
    • PUT /PATCH: for update operations
    • DELETE: for delete operations

On the other side, the server will issue a response to the client. The response usually holds the resource asked by the client, along with some headers and a response code. To keep things tidy and standard, HTTP uses the following response codes depending on the use case:

  • 1xx: Informational
    • 101: Switching Protocols
  • 2xx: indicates that the request went through
    • 200: ok
    • 201: resource created
  • 3xx: Redirects
    • 301: Moved Permanently
  • 4xx: indicates a client error
    • 403: Forbidden
    • 404: Resource not found
  • 5xx: indicates that the server has encountered an error while treating the request
    • 501: Server Error

JSON and common resource formats

The HTTP response code sent by the server usually comes along with a response body. Resources come in all kinds of forms; they can be HTML pages, PDF Files, images, video, sound, ...
When dealing with APIs, the server is decoupled from the client, hence knows little to nothing about the client querying it. The API is usually not designed for a sole client but should seek to serve a range of different clients.
JSON (Javascript Object Notation) is a popular lightweight format that is used through many APIs. It is associated so much with APIs that a common misunderstanding is that everything delivered through HTTP in a JSON format is REST. However, the resource format could be any sort of file format deliverable through HTTP; the key here is that the chosen format serves the consumers, is parsable and light.

REST

REST stands for REpresentational State Transfer and is a concept built around resources available through an application API. In the year 2000, Roy Fielding specified REST in his dissertation on network systems;  a RESTful API is determined by how closely it adopts the ideas (or constraints) of that dissertation (Ponelat et. al - Designing APIs with Swagger and OpenAPI). REST is a set of rules on how to design an API in an efficient way (the same manner Agile provides the guidelines for efficient team work for instance; by the way, REST is not limitted to HTTP API). It revolves around the concept of resources and aims at being  simple by decoupling the API from the underlying services that serve the API (API requests vs. normal requests).

Resources

Object Oriented Programming makes objects its first world class citizens, functional programming makes them functions; well, REST makes these resources. The resource, as described earlier, is what the server holds and that the client is interested in; it can be anything and is dependent on the business domain handled by the server. If this website holds a set of blog notes, these would be the resources the website API would deliver. A job posting portal might consider a job posting as its resources, a shop might make these the articles it sells.

Identifiers

I hope we now have wrapped our heads around the concept of first world citizens, i.e resources for REST. We know that the client will be asking for these through the API, therefore we need a way of identifying them and separating them from one another. Say a client is specifically interested in the current blog note about APIs and REST, there has to be some sort of identifier it can use in its query to access this particular blog note. Since we are using HTTP, the client is going to execute a request through an URI. The URI has to hold enough information to return the blog note of interest. To understand further REST, let’s explore two alternatives for the URI to use:

  • /api/showMeTheApiBlogNote : such a URI can be legit if it holds enough information to separate the API blog note from the other notes. The only problem with such an URI is that it is not resource-oriented. This is rather action-oriented or Remote Call Procedure (RPC) oriented. I am telling the server to execute an action instead of going through the concept of a resource
  • /api/blogNote/apiBlogNote : i like this format better because it holds 2 key concepts:
    • A resource, i.e. blogNote
    • The resource identifier, i.e. apiBlogNote
    • It adheres to the concept of resource-orientation that REST recommends

As you might have thought already, there is nothing wrong with the first alternative. It would work and probably return the same answer as the second option. However, it is all about principles and standardisation. If there is an implemented standard, clients will navigate much better through the API resources. 

Hierarchy

Once the resources are defined, it’s likely that these will have relationships between them (as tables in a relational database would have one /many to one /many  relationships). For instance, a blog note is owned by an author, or it belongs to a grouping of other related notes on the same topic.
How would one refer to blog notes of a specific author ? What if we need to see the notes that belong to a particular dossier? Should we consider that the notes are directly accessible, or accessed through their authors or through the enclosing dossiers? We need to model the relationships between the resource entities.
One option would be to use the notion of ownership; we would consider that an author owns a set of dossiers and that each dossier owns a set of notes.
There is a one to many relationship respectively between an author and dossiers, as well as one between a dossier and notes.
With such a model, the URI used to access the API resource note could look like this:

/api/authors/{authorID}/dossiers/{dossierID}/notes/{noteID}

This is one option amongst other potentially working alternatives; nevertheless, with such a model, we kept a resource-oriented approach, used identifiers and a fitting hierarchy.
However, since we have established that a resource is identified and accessed through its URI, composing the above URI can be tricky (on top of the hierarchy, one would need to be aware of several ids). HATEOAS (Hypermedia as the Engine of Application State) can serve this purpose; it is a concept of including hypermedia links within the returned resource to allow the client to further navigate the resource tree and make subsequent requests. For instance, an author resource could include a link to a listing of his/her dossiers, while the dossiers listing itself would include, for each dossier, a summary listing of owned blog items, with each note holding a consultation link.

Standard Methods

As explained earlier, standardisation is what we are seeking. REST goes a step further by imposing the use of standard methods to manipulate the API resources. The notions of HTTP, resources and identifiers come together through these standard methods. REST imposes us to adapt to its principles by manipulating these resources through standard methods.

Name

HTTP Verb

URI

RPC Meaning / Behavior

HTTP Response Code

Create

POST

api/notes

Create a new resource

201

Get

GET

api/notes/{id}

Retrieve an existing resource

200

List

GET

api/notes

List a collection of  resources

200

Update / Replace

PATCH* / PUT

api/notes/{id}

Change an existing resource

200

Delete

DELETE

api/notes/{id}

Remove an existing resource

200

*PATCH vs. PUT (according to Geewax's API Design Patterns)
The recommended way to update a resource relies on the HTTP PATCH method,  pointing to a specific resource using its unique identifier and returning the newly modified resource. One key aspect of the PATCH method is that it does partial modification of a resource rather than a full replacement. To accomplish this, the replace method uses the HTTP PUT verb rather than the PATCH verb targeted at the resource itself and provides exactly (and exclusively) the information meant to be stored in the resource. This full replacement, compared to the specific targeted modification provided by the standard update method, ensures that the remote copy of a resource looks exactly as expressed, meaning clients need not worry whether there are additional fields lingering around that they weren’t aware of.

Producing an API Description with OpenAPI and Swagger

API Producers need to describe their API for the consumers; for this, they can rely on OpenAPI, a specification to describe several aspects of an HTTP-based API such as:

  • the expected inputs
  • the outputs to be generated
  • the required authorization
  • ...

OpenAPI uses the YAML format to describe the API while Swagger is a set of tools to produce such a description file; an example of the resulting description file is shown below:

OpenApi Example

Conclusion

Now that we have introduced the notion of resources into our vocabulary, let’s go ahead and refine our descriptions:

  • A system that provides an interface for other computer systems exposes an API
  • An API is described through the OpenAPI Specification
  • HTTP is a set of rules for the exchange of resources on the web
  • An API may be an HTTP API or not
  • REST is a set of rules to design an API around the concept of resources
  • A RESTful API is one that respects the rules of REST
  • RPC is the concept of executing an action on the server; it is common in SOAP or AJAX requests
  • JSON is a file / document / resource format
  • A JSON file can be exchanged through HTTP without REST 
  • Swagger is a set of tools to describe an API

Using REST, the client is not looking to execute an action on the server API, but it should be seeking to access and / or manipulate a resource on the server. The server, on the other side, agrees to a contract to standardize access to its resources through a set of predefined methods.
Needless to say: "All this fuss for this! At the end, what’s the difference between GET api/showMeAllNotes and GET api/notes, if not just the used URI?"
Well, to such an interrogation, I would reply that the difference between a tidy system and a randomly put together system, the difference between controlled maintenance / evolution and technical debt often relies on the use of standards. REST is all about adopting a standard so as to scale easily and to ease the interactions between the producer and the consumer.
The operations falling out of the described standard operations would not be respecting the REST principles. The aim is therefore not to make stateless access to data in the JSON format, but to actually turn the API design in such a way that we only use the standard operations on the API resources. If a resource has a complex logic associated to it in such a way that the standard REST actions would not be fitting, the API designers need to find conceptual resources in such a way that one can execute standard REST methods on them. Such a shift can be counter intuitive and sometimes means walking away from the business objects as resources to designing a domain model fitted to the requirements of a RESTful API.

Further Reading Notes

  • Geewax - API Design Patterns
  • Ponelat et. al - Designing APIs with Swagger and OpenAPI includes the following excerpt:
    Where REST starts and HTTP ends is a tricky one to answer, but the rule of thumb is HTTP is the actual protocol and REST is a way of designing APIs. HTTP has incorporated many of the ideas of REST into its protocol, which is why they are so closely related...Typically  we'll more often note when a HTTP API is not RESTful, by that we mean it doesn't conform to the design patterns outlined by REST.

Share: