So all of this buzz starts from what is the REST API? But before that, we must have to understand what the hell is an API?

What is an API?

So-Called Definition:

API stands for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other.

What have you understood from this definition nothing right?, Just bear with me at the end of an article I am pretty sure that you will get a thorough understanding of this hazy topic.

Need for an API?

We have to use an API to communicate with various devices. Ex: If your application has to communicate with various things like web browsers, android devices, ios devices, or maybe windows devices, or if your application needs to communicate or use third-party software or services. So to fulfill all these requirements, you have to use an API.

Dive into API (API Explanation)

Just look at the picture above and it works exactly like that.

When you go to a restaurant and you would like to order food you first go to a waiter and say I would like to order some chicken wings and one large coke. The waiter will take the order and convey it to the chef in the kitchen and when the food is ready chef calls the waiter and the waiter will bring your food to your table. So in this case Waiter is your API that acts as a mediator which allows the communication between you and the chef.

IN TECHNICAL TERMS:

An API is software that can be used by other software, to communicate with other software or even hardware. It acts as a bridge between different software and devices.

So as per the above restaurant example, customer/you which is Client, Waiter which acts as an API and kitchen serves as a Backend/Server.

How does an API works?

APIs communicate through a set of rules/protocols that defines how computers, applications, or machines can talk to each other. It works over the internet via HTTP protocol which works on top of the TCP/IP protocol.

The easiest way to think about working on APIs is to take the above restaurant example: Customer, a Waiter, and a Restaurant Kitchen: A customer talks to the waiter and tells the waiter what she wants. The waiter takes down the order and communicates it to the kitchen. The kitchen does their work, creating the food, and then the waiter delivers the order back to the customer.

In this example, a customer is like a user, who tells the waiter what she wants. The waiter is like an API, receiving the customer’s order and translating the order into easy-to-follow instructions that the kitchen then uses to fulfill that order — often following a specific set of codes, or input, that the kitchen easily recognizes. The kitchen is like a server that does the work of creating the order in the manner the customer wants it, hopefully! When the food is ready, the waiter picks up the order and delivers it to the customer. For example, in a Web application, there is usually a Front End and a Back End, both of which can be developed using different languages like JavaScript for the frontend or Python for the backend. APIs are developed to help these two communicate and work in conjunction.

Building Blocks of an API

API architecture refers to a software building block that implements an API. For example, if we look at the TCP/IP protocol, many layers form the building block of this protocol stack. They are all arranged in a specific order. Individually, they perform a single, well-defined responsibility. But, collectively, they achieve the transmission of data between two devices through the Internet. Similar way API also has a specific responsibility to each block.

To better understand the API architecture, let us split the API responsibilities into individual entities accountable for them. In this way, we stitch the building blocks that define the generic API architecture.

API Interface Block: The Interface block is responsible for defining the specifications for the API. This is important for the external world to access the API. In most cases, these specifications are governed by the application layer protocol that hosts the API. HTTP is the most ubiquitous protocol that carries the API payload. Therefore the API interface is defined in terms of the API endpoint URL, the port number, and the HTTP method. The API interface also defines additional HTTP headers.

API Controller Block: Beyond the interface, an API needs to control the ingress and egress traffic. This is where the API request and responses are interpreted, and additional control mechanisms are applied via the Controller block. Some of the most apparent control mechanisms include rate limiting, throttling, blacklisting. This is to ensure that the client applications do not misuse the API. It also guards against abuse of the API. Even more important is the handling of unauthorized access to API. Therefore this building block is also responsible for authentication and authorization. Additionally, it can peek inside the HTTP headers and data payloads to perform additional checks and transformations.

API Runtime Block: The Runtime block takes care of the computing responsibility of the API. Behind the scenes, every API is a piece of software that performs a well-defined business logic serving the needs of the API’s client. Depending upon a chosen programming language and its toolchain, a runtime environment gets spawned. Then, the business logic execution happens inside this runtime environment, supported by additional configuration data and environment variables.

API Data Bridge Block: Usually, the data storage engines, like the databases or any form of data store, are universally shared between the individual APIs that form the API service. This approach ensures that there is a single source of truth across all APIs. The APIs must have a bridge between their runtime block and the data engine to facilitate seamless access to data. The Data Bridge block is responsible for orchestrating this data access. The actual implementation of this block is platform-specific and depends on database drives and programming libraries. These are managed from within the Runtime block. An additional component that plays a very crucial role in API design is called API Management.

What is an API Management?

API management is the process of designing, publishing, documenting, and analyzing APIs in a secure environment. Through an API management solution, an organization can guarantee that both the public and internal APIs they create are consumable and secure.

API management refers to the processes for distributing, controlling, and analyzing the APIs that connect applications and data across the enterprise and clouds. The goal of API management is to allow organizations that create APIs or use others’ APIs to monitor activity and ensure the needs of the developers and applications using the API are being met.

Components of an API management

API design: API management solutions provide users — from developers to partners — the ability to design, publish and deploy APIs as well as record documentation, security policies, descriptions, usage limits, runtime capabilities, and other relevant information.

API Gateway: Routing of requests, composition, protocol translation, and other common API services tasks occur, which acts as a gatekeeper for all APIs by enforcing relevant API security policies and requests and also guarantees authorization and security.

API Store /Developer Portal: API management solutions provide users with the ability to keep their APIs in a store or catalog where they can expose them to internal and/or external stakeholders. This API “store” then serves as a marketplace for APIs, where users can subscribe to APIs, obtain support from users and the community, and so on.

API Analytics/Dashboard: API management allows users to monitor API usage, load, transaction logs, historical data, and other metrics that better inform the status as well as the success of the APIs available.

Types of an API

Open API: Also known as Public API, there are no restrictions to access these types of APIs because they are publicly available.

Partner API: A developer needs specific rights or licenses to access this type of API because they are not available to the public.

Internal API: Also known as Private APIs, only internal systems expose this type of API. These are usually designed for internal use within a company. The company uses this type of API among the different internal teams to be able to improve its products and services.

What is REST API?

Today, there are three categories of API protocols or architectures: REST, RPC, and SOAP. These may be dubbed “formats,” each with unique characteristics and tradeoffs and employed for different purposes.

But in this article, we will be solely focusing on REST API/ARCHITECTURE. So now you would be probably thinking we just freaking finished the API part and now what the hell is REST so guys please just sit back and relax I would explain the whole buzz of REST so there is no rocket science happening beneath REST API.

So first let me clear that REST is more of a convention than a specification. It is a style and not specification.

A REST API is an application programming interface (API) that uses a representational state transfer (REST) architectural style. The REST architectural style uses HTTP to request access and use data. This allows for interaction with RESTful web services.

The concept of REST was introduced in 2000 by Roy Fielding, a noted computer scientist who has influenced the development of many WWW standards. REST was, and remains, a core architectural principle for the web in general. REST APIs are popular because they are user-friendly and easy to understand. REST is now considered the standard protocol for web APIs. And REST APIs are often used instead of SOAP APIs.

REST API Architecture Breakdown

REST works on top of HTTP. It takes advantage of HTTP’s native capabilities, such as GET, PUT, POST, and DELETE. So REST API works in this manner, First REST client sends a REST request with its desired HTTP method for requesting a particular resource to one particular REST server endpoint and in return, the REST server sends back the response which is in XML or JSON format.

REST Client: Code or an app that can access these REST services. You are using one right now! Yes, the browser can act as an uncontrolled REST client (the website handles the browser requests). The browser, for a long time, used an in-built function called XMLHttpRequest for all REST requests.

REST Server: Offers an API as a means of access to its data or features; and a resource, which is any piece of content that the server can provide to the client (for example, a video or a text file). REST API: This defines the endpoint and methods allowed to access/submit data to the server. Now you would be thinking about what is endpoint.

Endpoint/URI: Simply put, an endpoint is one end of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. An endpoint contains a Uniform Resource Identifier (URI) indicating where and how to find the resource on the Internet. The most common type of URI is a Unique Resource Location (URL), serving as a complete web address.

REST Request: Any REST request includes four essential parts: an HTTP method, an endpoint, headers, and a body.

An HTTP method describes what is to be done with a resource and it is also referred to as a Resource Method. There are four basic methods also named CRUD operations:

→ POST to create a resource,

→ GET to retrieve a resource,

→ PUT to update a resource, and PATCH for doing a partial update, we can use HTTP PATCH. For instance, when updating a single field of the Resource,

→DELETE to Delete a resource.

Headers store information relevant to both the client and server. Mainly, headers provide authentication data — such as an API key, the name or IP address of the computer where the server is installed, and the information about the response format. A body is used to convey additional information to the server. For instance, it may be a piece of data you want to add or replace.

REST Response Structure: In response, the server sends not the sought-for resource itself, but its representation — a machine-readable description of its current state. The same resource can be represented in different formats, but the most popular ones are XML and JSON. Whenever relevant, a server includes in the response hyperlinks or hypermedia that links to other related resources. This way, the server gives instructions on what the client can do next and what further requests it can make.

or the response will be in JSON format as shown in the below image:

Constraints that make an API Restful

Sometimes have noticed that there are many API on the internet which is proclaimed to be RESTful but that is not quite true. There is a huge misconception going on that all APIs that are communicating over HTTP is REST.

REST!=HTTP

Unlike REST, the HyperText Transfer Protocol (HTTP) is a standard with well-defined constraints. HTTP is the communication protocol that powers most of our everyday interactions on the internet.

-> Web browsers loading web pages

-> Streaming a video

-> Using a mobile device to turn off the lights in a home

So, is REST the same thing as HTTP? The short answer is no. HTTP is a protocol that is maintained by the Internet Engineering Task Force(IETF). While it is not the same as REST, it exhibits many features of a RESTful system. It’s important to remember that the use of HTTP is not required for a RESTful system. It just so happens that HTTP is a good starting because it exhibits many RESTful qualities like the HTTP methods (GET, PUT, POST, etc.)

A well-written and well-explained article that I have found on medium explains what are the constraints that make a difference in REST VS NON-REST API.

https://towardsdatascience.com/rest-api-the-architectural-constraints-fc4876b41e3d

REST API Best Practices

1. Use JSON as the Format for Sending and Receiving Data

Because it is more lightweight compared to XML and it saves a bit more bandwidth than the XML.

In the past, accepting and responding to API requests were done mostly in XML and even HTML. But these days, JSON (JavaScript Object Notation) has largely become the de-facto format for sending and receiving API data.

This is because, with XML for example, it’s often a bit of a hassle to decode and encode data — so XML isn’t widely supported by frameworks anymore. JavaScript, for example, has an inbuilt method to parse JSON data through the fetch API because JSON was primarily made for it.

But if you are using any other programming language such as Python or PHP, they now all have methods to parse and manipulate JSON data as well. For example, Python provides JSON.loads() and JSON.dumps() for working with JSON data. To ensure the client interprets JSON data correctly, you should set the Content-Type type in the response header to application/JSON while making the request. For server-side frameworks, on the other hand, many of them set them Content-Type automatically. Express, for example, now has the express.json() middleware for this purpose. The body-parser NPM package still works for the same purpose, too.

2. Use Nouns Instead of Verbs in Endpoints

When you’re designing a REST API, you should not use verbs in the endpoint paths. The endpoints should use nouns, signifying what each of them does.

This is because HTTP methods such as GET, POST, PUT, PATCH, and DELETE are already in verb form for performing basic CRUD (Create, Read, Update, Delete) operations.

GET, POST, PUT, PATCH, and DELETE are the commonest HTTP verbs. There are also others such as COPY, PURGE, LINK, UNLINK, and so on.

So, for example, an endpoint should not look like this: mysite.com/getPosts or mysite.com/createPost Instead, it should be something like this: mysite.com/posts In short, you should let the HTTP verbs handle what the endpoints do. So GET would retrieve data, POST will create data, PUT will update data, and DELETE will get rid of the data.

3. Name Collections with Plural Nouns

You can think of the data of your API as a collection of different resources from your consumers. If you have an endpoint, it might be okay for deleting a post with a DELETE request or updating a post with a PUT or PATCH request, but it doesn’t tell the user that there could be some other posts in the collection. This is why your collections should use plural nouns. So, instead of mysite.com/post/123, it should be mysite.com/posts/123.

4. Use Status Codes in Error Handling

You should always use regular HTTP status codes in response to requests made to your API. This will help your users to know what is going on — whether the request is successful if it fails, or something else.

HTTP defines these standard status codes that can be used to convey the results of a client’s request. The status codes are divided into five categories. 1xx: Informational — Communicates transfer protocol-level information. 2xx: Success — Indicates that the client’s request was accepted successfully. 3xx: Redirection — Indicates that the client must take some additional action to complete their request. 4xx: Client Error — This category of error status codes points the finger at clients. 5xx: Server Error — The server takes responsibility for these error status codes.

5. Use Nesting on Endpoints to Show Relationships Oftentimes, different endpoints can be interlinked, so you should nest them so it’s easier to understand them. For example, in the case of a multi-user blogging platform, different posts could be written by different authors, so an endpoint such as mysite.com/posts/author would make a valid nesting in this case. In the same vein, the posts might have their comments, so to retrieve the comments, an endpoint like mysite.com/posts/postId/comments would make sense. You should avoid nesting that is more than 3 levels deep as this can make the API less elegant and readable.

6. Use Filtering, Sorting, and Pagination to Retrieve the Data Requested

Sometimes, an API’s database can get incredibly large. If this happens, retrieving data from such a database could be very slow. Filtering, sorting, and pagination are all actions that can be performed on the collection of a REST API. This lets it only retrieve, sort, and arrange the necessary data into pages so the server doesn’t get too occupied with requests.

An example of a filtered endpoint is the one below: mysite.com/posts?tags=javascript This endpoint will fetch any post that has a tag of JavaScript. Spotify does their pagination in this way:

7. Be Clear with Versioning

REST APIs should have different versions, so you don’t force clients (users) to migrate to new versions. This might even break the application if you’re not careful. One of the commonest versioning systems in web development is semantic versioning.

An example of semantic versioning is 1.0.0, 2.1.2, and 3.3.4. The first number represents the major version, the second number represents the minor version, and the third represents the patch version. Many RESTful APIs from tech giants and individuals usually come like this: mysite.com/v1 for version 1 mysite.com/v2 for version 2.

Facebook does their versioning in this way:

8. Provide Accurate API Documentation

When you make a REST API, you need to help clients (consumers) learn and figure out how to use it correctly. The best way to do this is by providing good documentation for the API.

The documentation should contain: -> relevant endpoints of the API

-> example requests of the endpoints

-> implementation in several programming languages

-> messages listed for different errors with their status codes

One of the most common tools you can use for API documentation is Swagger. And you can also use Postman, one of the most common API testing tools in software development, to document your APIs.

ZOOM does their API documentation in this way:

How to Secure your Well Designed REST API?

Why is API security important?: Businesses use APIs to connect services and transfer data. APIs that are broken, exposed, or hacked can expose sensitive medical, financial, and/or personal data. Thus, security is a paramount consideration when designing and developing RESTful and other APIs. Furthermore, there are many other ways to abuse APIs than a breach of the backend system. If an API is not properly secured, a variety of attacks can occur.

1. Keep it Simple

Secure an API/System just how secure it needs to be. Every time you make the solution more complex “unnecessarily,” you are also likely to leave a hole.

2. Always Use HTTPS

What Is HTTPS: HTTPS stands for Hypertext Transfer Protocol Secure (also referred to as HTTP over TLS or HTTP over SSL). HTTPS uses TLS (or SSL) to encrypt HTTP requests and responses, so instead of plaintext, an attacker would see a series of seemingly random characters.

TLS uses a technology called public-key encryption: there are two keys, a public key, and a private key. The public key is shared with client devices via the server’s SSL certificate. The certificates are cryptographically signed by a Certificate Authority (CA), and each browser has a list of CAs it implicitly trusts. Any certificate signed by a CA in the trusted list is given a green padlock lock in the browser’s address bar because it is proven to be “trusted” and belongs to that domain. Companies, like Let’s Encrypt, have now made the process of issuing SSL/TLS certificates free.

When a client opens a connection with a server, each machine needs a verified identity. So, the two devices use the public and private keys to agree on new keys, called session keys, to encrypt further communications between them. All HTTP requests and responses are then encrypted with these session keys so that anyone who intercepts communications can only see a random string of characters, not the plaintext.

By always using SSL, the authentication credentials can be simplified to a randomly generated access token. The token is delivered in the username field of HTTP Basic Auth. It’s relatively simple to use, and you get a lot of security features for free.

If you use HTTP 2, to improve performance — you can even send multiple requests over a single connection, that way you avoid the complete TCP and SSL handshake overhead on later requests.

3. Authorization Using JWT

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Authorization is the most common scenario for using JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single Sign-On is a feature that widely uses JWT nowadays, because of its small overhead and its ability to be easily used across different domains.

4. Never expose information on URLs

Usernames, passwords, session tokens, and API keys should not appear in the URL, as this can be captured in web server logs, which makes them easily exploitable.

https://api.domain.com/user-management/users/{id}/someAction?apiKey=abcd123456789  //Very BAD !!

The above URL exposes the API key. So, never use this form of security.

5. Consider OAuth

Though basic auth is good enough for most of the APIs and if implemented correctly, it’s secure as well — yet you may want to consider OAuth as well.

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service or by allowing the third-party application to obtain access on its behalf.

6. Consider Adding Timestamp in Request

Along with other request parameters, you may add a request timestamp as an HTTP custom header in API requests. The server will compare the current timestamp to the request timestamp and only accepts the request if it is after a reasonable timeframe (30 seconds, perhaps).

This will prevent very basic replay attacks from people who are trying to brute force your system without changing this timestamp.

7. Input Parameter Validation

Validate request parameters on the very first step, before it reaches application logic. Put strong validation checks and reject the request immediately if validation fails, In API response, send relevant error messages and examples of correct input format to improve user experience.

8. Rate Limiting

It is used for securing a backend from bombarding with much more requests and to ensure that client doesn’t abuse the API. Because if the client bombards the API then it is possible that our backend server gets crash and will go down and that will cost you a lot. So by putting a rate limit on your API it would save you from doing that.

Example:

X-RateLimit: Max requests allowed in a given period

X-RateLimit-Remaining: Requests remaining in a given period

X-RateLimit-Reset: Time remaining in the current period

Pros & Cons of REST API

PROS:

1. Easy to integrate: A decent RESTful API may be found from the very first URI. This isn’t to say that each application that uses your service will know what to do automatically. It does, however, make things easier for the developer who is attempting to connect your API.

2. Use of HTTP: The usage of ubiquitous standards is another characteristic for ease of integration that has to do with REST over HTTP (THE most popular implementation of REST). Speaking of HTTP, the web’s protocol, and outputting JSON or ATOMPub means finding a library that can connect to you in any language and the platform is much easier.

3. Scalability: This protocol stands out due to its scalability. Thanks to the separation between client and server, a product may be scaled by a development team without much difficulty.

4. Flexibility and portability: With the indispensable requirement for data from one of the requests to be properly sent, it is possible to perform a migration from one server to another or carry out changes on the database at any time. Front and back can therefore be hosted on different servers, which is a significant management advantage.

5. Independence: With the separation between client and server, the protocol makes it easy for developments across a project to take place independently. In addition, the REST API adapts at all times to the working syntax and platform. This offers the opportunity to use multiple environments while developing.

6. Uniform Interface: When creating a REST API, developers agree to follow the same standards. Hence, the output is a consistent interface across all APIs. This interface functions as a contract between the client and the service, and it is shared by all REST APIs. How is this useful? When developers utilize APIs, they require global ideas to ensure that they can communicate with one another.

CONS:

1. Convention Not A Specification: As I said previously REST is purely a convention, So it is possible to delete a resource from the backend even if your HTTP request method is for updating a resource (PUT), So the misuse of the request method is possible.

2. Lack of state: Most web applications require stateful mechanisms. Suppose you purchase a website that has a mechanism to have a shopping cart. It is required to know the number of items in the shopping cart before the actual purchase is made. This burden of maintaining the state lies on the client, which makes the client application heavy and difficult to maintain.