In this article, I would like to introduce to the reader, REST APIs. REST is an acronym for Representational State Transfer. It is a standard of communication between a resource consumer (browsers, apps) and a resource provider (servers). REST API plays a vital role in modern web development by providing a simple, scalable, and interoperable approach to building web services. I hope to briefly explain the nature of REST as well as a few of its technicalities. In subsequent articles, we would build a simple REST API and apply the knowledge explained here. Before I delve into further details, let me explain a few things about the web.

How the Internet Works

On a very basic level, this is how the internet works: A client (usually a browser, mobile app, desktop app, etc) sends a request to a server requesting for resources (usually web pages, data, etc). Then, the server sends an HTTP response, which includes the requested resource if successful or an error message if not. The Role of REST in Web Communication This article will focus on the web. On the web, as we’ve established before, the browser talks to the server with one or more requests for certain resources it needs to load a webpage or display some data. The server then responds with the requested resources or an error message when something goes wrong. In all of these, there needs to be a standard whereby the server knows how the client (browser) would send its request so that it can understand it and respond accurately. Also, the same goes for the client, it needs to know in what way the server will respond with the resources requested so that it can understand and use them accordingly. REST serves as a standard communication protocol between client and server, ensuring both parties understand how to exchange data effectively.

The Structure of a REST Request

A basic client REST request will have the following components: Headers, Operations, Endpoint, Parameters and Body.
All of these terms will be briefly explained.

Headers

The headers give more information to the server about what type of data is coming in, tokens for access to the resource requested and so on. Headers can be written in this manner:

Operations

There are a few operations that can be performed in a request. They are denoted by the following HTTP verbs: GET, POST, PUT, PATCH and DELETE. These operations indicate to the server what operation the request is to perform and whether or not it has other components of a request. For instance, a GET request is not going to have a request body because it is a request for a resource and not a storage or update of a resource.

Endpoint

This is the URL that points to where the resource or resources needed is located. For instance, the URL https://www.google.com/ points to the resource that is the homepage of the Google Search Engine. Every REST request must be directed to an endpoint.

Parameters

Parameters usually give more context and information to the REST endpoint. There are about three examples of parameters in a REST API setting, they are:

Query parameters

These are parameters added to the endpoint URL. For instance, if you did a quick Google Search about “database”, if you look at the URL bar of your browser, you should see something like this: https://www.google.com/search?q=database. The “?q=database” part is the query parameter giving more information to the server serving the resource(s) requested. In this case, it is telling the Google server that it is searching for resources related to the name “database”. The server then provides all such resources.

Path Parameters

These are parameters passed as part of the endpoint, similar to query parameters, only that these form part of the endpoint and are not an optional part of the endpoint as they communicate a piece of essential information to the server. For instance, if you want to request a resource in a database with a particular ID, it is standard practice to pass that ID as a path parameter rather than a query parameter. For example, let’s assume you have a database of books and you want to get the book with an ID of 5. Your request from your client will be a GET request to the endpoint that looks like http://your-domain/books/{ID}; in this case, ID = 5.

Body

This is usually JSON formatted data that provides large data sets of information. It is usually sent to endpoints that serve to create or update records as in such instances, you might have to send a lot of data. An example of body data is:

The Structure of a REST Response

When a request is made to a server or resource provider, a response is expected and necessary. In this case, a response is always given to every API request even if things go wrong. These responses also follow a standard and structure, as such, have some necessary as well as optional elements.

A basic structure of a REST response includes:

Status Code

This is an essential part of a REST API’s response to a request for a resource. Status codes consist of three numbers which are in the format of 1XX, 2XX, 3XX, 4XX and 5XX. Those three numbers convey a lot of information on their own. For instance, a status code of 200 means OK; 201 means Resource created; 400 means Bad Request; 502 means Bad Gateway. So, by agreeing on these standards, software engineers can tell by just seeing the status code whether a request was successful or not and if not, a potential area where the problem stems from.

Headers

Much like for the request, the headers for a response give more information to the client about the response data sent with the same options as for the request.

Body/Data

This includes the data from the server which could include the resource requested, created, updated or nothing in the case of a DELETE request.

Conclusion

I hope that I have been able to explain in not verbose terms what a REST API is and its major components. The key points are these:

• REST is a standard of web communication between clients and the server.

• Every HTTP request from a client has a standard structure that includes: Headers, Operations, Endpoints and Parameters.

• Every HTTP response from the server has a standard structure that includes: Headers, Status Code, Headers and Body/Data.

In the next article, I hope to build a simple Books API and show the practicality of some of the software languages used here.

Thank you for your time.

Oluwadara, OLOYE.