What is an api?

API stands for Application programming Interface. In simple terms, it is a pathway that connects one application, or user, to your application. The specific point of connection may be called an endpoint. Think of a power grid, for example, with all its components. There are generators, the cables, the transformers, the meters, the monitors and all other components. To use it, well, you can even connect to the grid illegally via overhead attahing of your cables to the main three-phase supply cable lines, but that may not end well. There is a secure and legal way for all, safe and usable by any user despite their knowledge or lack of knowledge of how power reaches them - the socket. Switching on and off the socket supplies and cuts power supply to the appliances or the house. While inventing an appliance like a microwave, you only need to know how it will consume the electricity rather than how the electricity is produced. On the other hand, also, the power generators and suppliers do not need to know which appliances are to be used, they only need to supply power in a good range that can be assimilated and customized to the user's needs, such as stepping it down, converting to DC current, and others.

This is how apis work. An application made is complete in itself, testable and serves its own purpose to the owner. However, the user may decide to expose a way to share their data, or functions, or otherwise, (or receive from other applications) so as to effectively run. For instance, an application may require clients' data to be authenticated by an external module or system so as not to have to create an authentication module that may be hard to maintain. Thats where an interface for this interaction comes in. The endpoint becomes the handshake connection that is provided to link the two services or applications. The api defines a set of rules, configurations and protocals that are required for this integration, defining the requirements of the integration, and the expected responses from the integration of the software.

RESTful APIs

REST stands for Representational State Transfer. Now, this doesn't sound really pretty. But basically, it means that when an integrating software, such as a client application, requests for some data (resource) from an api, the api transfers the state of the requested resource in a specific standardized representation. For instance, a client may request for a name of a product, and request to be returned in json format, list form, etc. The api receives the requests, and responds in a standardidex defined manner to the satisfaction of the client. To avoid getting really technical here (because this post is about non-technical terms of technical issues), I will skip the part that REST apis use a specific protocal for responses and requests for clear predictable responses. Most REST apis use HTTP, a protocal developed to transfer data over the internet in form of hyper text.

Mainly, RESTful has been pushed further to imply its procedure of making calls and receiving responses. Unlike other apis that we will discuss later in another article, RESTful apis are in this manner - the client (the application requesting for a resource from a server. May be a client interface app, or another backend microservice) requests for a resource, then waits and maintains connection until the server returns a response to the request. There must be a request followed by a response within a single connection. It sort of rests to wait for a response, instead of continuing with other work. For instance, if an application has a code to call a restful api in the middle of a code block, the rest of code block will only execute once the call has returned an appropriate response. This means that inorder to control the amount of time of these operations, restful apis have a timeout configurations and maximum retries in case of loss of connection to the server api, that return specified codes and statuses.

So as to keep waiting for the response from a server, most javascript applications use asynchronous tools and promises to await for a response before proceeding with the code execution. This is to mean that, although the call to the server has technically completed in tis connection, the immediately returned response is a Promise of a response from the server, which may be fulfilled or may fail depending on the response. Therefore, when javascript promises are returned, they command the code to wait there for the response and only perform the rest of actions after the response has been returned. This difference will be clear in the next post, where we will be discussing concurrent calls and the messaging protocals, and event-driven architectures for calls. For rest, it all means that the request can only be considered complete once the response is received back to the client that rewuest for the resource.

With that, I let this REST.