DEV Community: Ishant Gaurav

REST-API Design Best Practices

Ishant Gaurav — Mon, 08 May 2023 03:04:45 +0000

In this world of microservice, we develop most of endpoints using the REST(Representational State Transfer)-architecture for one mircroservice to talk to other microservice. So it is imperative to have good command on designing the REST-API in such a way which are meaningful, easy to extend and backward compatible.

If you like watching a video, then you can watch the same on my youtube channel : .

In this post, we will talk some of the best practices, which we should consider while designing any new REST API.

USE NOUN INSTEAD OF VERBS IN ENDPOINT PATHS

We shouldn’t use verbs in our endpoint paths. Instead, we should use the nouns which represent the entity that the endpoint that we’re retrieving or manipulating as the pathname.

Why So ?

This is because our HTTP request method already has the verb. Having verbs in our API endpoint paths isn’t useful and it makes it unnecessarily long since it doesn’t convey any new information. The chosen verbs could vary by the developer’s whim. For instance, some like ‘get’ and some like ‘retrieve’, so it’s just better to let the HTTP GET verb tell us what and endpoint does.

The action should be indicated by the HTTP request method that we’re making. The most common methods include GET, POST, PUT, and DELETE.

GET : retrieves resources.
POST : submits new data to the server.
PUT : updates existing data.
DELETE : removes data

UNDERSTAND THE SEMANTICS OF THE HTTP METHODS

Definition of Idempotence: A HTTP methods is idempotent when we can safely execute the request over and over again and all requests lead to the same state.

GET

Idempotent
Read-only. GET never changes the state of the resource on the server-side. It must not have side-effects. Hence, the response can be cached safely.

Examples:

GET /users – Lists all users GET /users/1 – Shows the details of the user 1

PUT

Idempotent!
Can be used for both creating and updating
Commonly used for updating (full updates).

Example: PUT /users/1 – updates user 1 (uncommon: creates user 1)

To use PUT for creating, the client needs to know the whole URL (including the ID) upfront. That’s uncommon as the server usually generates the ID. So PUT for creating is typically used when there is only one element and the URL is unambiguous.

Example: PUT /user/1/avatar – creates or updates the avatar of user 1. There is only one avatar for each user.
Always include the whole payload in the request. It’s all or nothing. PUT is not meant to be used for partial updates (see PATCH).

POST

Not idempotent!
Used for creating
Example: POST /user creates a new user. The new URL is delivered back to the client in the Location Header (e.g. Location: /user/12). Multiple POST requests on /users lead to many new different users (that’s why POST is not idempotent).

PATCH

Idempotent
Used for partial updates. Example: PATCH /users/1– updates users 1 with the fields contained in the payload. The other fields of users 1 are not changed.

DELETE

Idempotent
Used for deletion.
Example: DELETE /users/1

For example :

GET /users – Retrieves a list of users
GET /users/12 – Retrieves a specific user
POST /users – Creates a new user
PUT /users/12 – Updates user #12
PATCH /users/12 – Partially updates user #12
DELETE /users/12 – Deletes user #12

Note : Although we should use verb in the method name always be using verbs and same will be applied for resource method like createUser, updateUser etc.

ALWAYS MAKE THE ENDPOINT NAME PLURAL

We should name collections with plural nouns. It’s not often that we only want to get a single item, so we should be consistent with our naming, we should use plural nouns.

Why So ?

We use plurals to be consistent with what’s in our databases. Tables usually have more than one entry and are named to reflect that, so to be consistent with them, we should use the same language as the table the API accesses.In the example below, we always use /users to represent the entity so that it would be consistent across all kind of endpoints.

GET /users – Retrieves a list of users GET /users/12 – Retrieves a specific user

/users —-> represent all the users
/users/{id} —> represent the single entity

HIERARCHICAL OBJECTS OR RELATION BETWEEN OBJECTS

The path of the endpoints that deal with nested resources should be done by appending the nested resource as the name of the path that comes after the parent resource.We have to make sure that it makes sure what we considered a nested resources matches what we have in our database tables. Otherwise, it’ll be confusing.

For example if we have to find the all the list of the cars which a user posses then the endpoint path would be as :

GET : /users/{userId}/cars —- fetch all the cars of a particular
GET: /user/{userId}/cars/{carId} — fetch the details of a particular car.

USE THE QUERY STRING (?) FOR OPTIONAL AND COMPLEX PARAMETERS

Keep your URLs simple and the URL set small. Choose one base URL for your resource and stick to it. Move complexity or optional parameters to the query string.

GET /users?state=internal&title=senior GET /users?id=1,2

REST API VERSIONING

You’ve already written your REST API and it has been very successful and many people have used it and are happy with it. But you have that juicy new functionality that breaks other parts of the system.

Versioning allows you to release incompatible and breaking changes of your API under a new version without breaking the clients. They can continue consuming the old version. The clients can migrate to the new version at their own speed.

If you are building internal APIs you most likely know all of your clients. So performing breaking changes can be an option again. But it will require more communication and a coordinated deployment.

URI versioning :

Versioning is usually done with /v1/, /v2/, etc. added at the start of the API path.

Before you start making your API, you can version your API by prefixing the endpoints by the API version: https://ishant.gaurav.com/v1/authors/2/blogposts/13

This way you can always increment your API version number (eg. v2, v3…) whenever there are breaking changes in your API. This also signals to the users that something drastic has changed and they should be careful when using the new version.

Pros: Clients can cache resources easily
Cons: This solution has a pretty big footprint in the code base as introducing breaking changes implies branching the entire API

Query string versioning

Instead of providing multiple URIs, you can specify the version of the resource by using a parameter within the query string appended to the HTTP request, such as https://ishant.gaurav.com/authors/2/blogspots/13?version=2. The version parameter should default to a meaningful value such as 1 if it is omitted by older client applications.

Advantage of using the versioning in URI is that the URI need to be changed for different versions of API but it also depends on the code that handles the request to parse the query string and send back the appropriate HTTP response.

Pros: It’s a straightforward way to version an API, and it’s easy to default to the latest version
Cons: Query parameters are more difficult to use for routing requests to the proper API version

Header versioning

Another way to implement the API versioning is that you could implement a custom header that indicates the version of the resource. This approach requires that the client application adds the appropriate header to any requests, although the code handling the client request could use a default value (version 1) if the version header is omitted.

Version 1:

GET https://ishant.gaurav.com/authors/2/blogspots/13 HTTP/1.1 Custom-Header: api-version=1

Version 2:

GET https://ishant.gaurav.com/authors/2/blogspots/13 HTTP/1.1 Custom-Header: api-version=2

Pros: It doesn’t clutter the URI with versioning information
Cons: It requires custom headers

Media type versioning (Accept Header)

Another way to define the api versioning is via the media type. Accept header define the media type and character encodings. We can also pass version information for Web API through accept headers without changing the URL. It is also known as media type versioning or content negotiation or accept header. Github uses the accept header versioning.

Accept: application/vnd.demo.v1+json Accept:application/vnd.demo+json;version=1.0

Pros: Allows us to version a single resource representation instead of versioning the entire API, which gives us a more granular control over versioning. Creates a smaller footprint. Doesn’t require implementing URI routing rules.

Cons: Requiring HTTP headers with media types makes it more difficult to test and explore the API using a browser.

USE HTTP STATUS CODES

The RESTful Web Service should respond to a client’s request with a suitable HTTP status response code.

2xx – success– everything worked fine.
4xx – client error – if the client did something wrong (e.g. the client sends an invalid request or he is not authorized)
5xx – server error – failures on the server-side (errors while trying to process the request like database failures, dependend services are not available, programming errors or states that should not occur)

Consider the available HTTP status codes. However, be aware, that using all of them could be confusing for the users of your API. Keep the set of used HTTP status codes small. It’s common to use the following codes:

2xx: Success

200 OK
201 Created

3xx: Redirect

301 Moved Permanently
304 Not Modified

4xx: Client Error

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
410 Gone

5xx: Server Error

500 Internal Server Error

Don’t overuse 404. Try to be more precise. If the resource is available, but the user is not allowed to view it, return a 403 Forbidden. If the resource existed once but now has been deleted or deactivated, use 410 Gone.

PROVIDE USEFUL ERROR MESSAGES

Additionally to an appropriate status code, you should provide a useful and verbose description of the error in the body of your HTTP response. Here’s an example.

Request:

GET /employees?state=super

Response:

// 400 Bad Request
{
  "errors": [
    {
      "status": 400,
      "detail": "Invalid state. Valid values are 'internal' or 'external'",
      "code": 352
    }
  ]
}

DOCUMENTATION

This one is a no-brainer. You could be the best API designer in the world, but without documentation, your API is as good as dead. Proper documentation is essential for every software product and web service alike.

You can help the user by being consistent and using clear and descriptive syntax, sure. But there is no real replacement for good ol’ documentation pages.

Here are some of the great examples:

There are many tools that can help you document your API, but don’t forget to add the human touch, only one human can properly understand another.

This is all from this POST, please give your comments and thoughts about it in the comments.

Create a JVM microservice in less than 10MB with Micronaut

Ishant Gaurav — Wed, 07 Jul 2021 15:08:17 +0000

In this blog post, we will create a simple hello-world microservice by using the Micronaut framework. We will explore why Micronaut has gained so much popularity in the last few years despite being the presence of other famous framework like Spring, Dropwizard etc.

Micronaut is a modern, JVM based, full-stack framework for building modular, easily testable microservice applications. Micronaut integrates cloud technologies into the framework, and microservice patterns such as service discovery, distributed tracing, circuit breaker are baked into the framework.

Micronaut has 100% compile-time, reﬂection free, dependency injection and AOP. Thus, Micronaut applications are small and have a low memory footprint.

This post was first posted on : https://ishantgaurav.in/

Let’s create a simple microservice and deploy it to learn how Micronaut work. Later on we will also verify the cold boot time and memory foot print of the created microservice using VisualVM tool.

I will be using the micronaut-cli tool to create the micronaut application. You can install and read about it from here Micronaut Command Line Interface.

Run the below command to create new micronaut microservice.

mn create-app ishant.micronaut.sample-service --build=maven --lang=java

Once your above command is complete, you will have an application created like this.

Once the application is created we would have two main file which we need to look upon:

pom.xml :

We can see in the pom file that, by default micronaut install few dependencies like validation, test, http and http-server etc.

<dependencies>
    <dependency>
      <groupId>io.micronaut</groupId>
      <artifactId>micronaut-inject</artifactId>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.micronaut</groupId>
      <artifactId>micronaut-validation</artifactId>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-engine</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>io.micronaut.test</groupId>
      <artifactId>micronaut-test-junit5</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>io.micronaut</groupId>
      <artifactId>micronaut-http-client</artifactId>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.micronaut</groupId>
      <artifactId>micronaut-http-server-netty</artifactId>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.micronaut</groupId>
      <artifactId>micronaut-runtime</artifactId>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <scope>runtime</scope>
    </dependency>
  </dependencies

We can see in the pom file that, by default micronaut install few dependencies like validation, test, http and http-server etc.

Application.java

package ishant.micronaut;

import io.micronaut.runtime.Micronaut;

public class Application {

    public static void main(String[] args) {
        Micronaut.run(Application.class, args);
    }
}

Now let’s create a simple GET controller to return “Hello Micronaut” as below:

HelloController.java

package ishant.micronaut;

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;

@Controller("/hello")
public class HelloController {

    @Get
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello Micronaut";
    }
}

As our controller is created, now we will deploy and our application via IntelliJ idea itself and also we will make the maximum memory allocation to 10 MB.

Once the application is deployed, let’s go to VisualVM check the memory foot print of our microservice.

Memory Foot Print :

As you can see in the Heap space of our sample-service, it is only taking 7.2 MB, which is even less than the maximum space of 10MB which we allocated to this microservice.

Cold Boot Time :

From the above image, we can see the cold boot time of our sample service is 1.9s which would be more less if you have good configuration in your system. I am running this on Ubuntu 20.04, 8 GB Ram and i5 processor.

Conclusion

So we saw how Micronaut can help in developing cloud native microservice, which has very less foot print and the cold boot time. Micronaut achieved this through the use of Java’s annotation processors, which are usable on any JVM language that supports them, as well as an HTTP Server and Client built on Netty. To provide a similar programming model to Spring and Grails, these annotation processors precompile the necessary metadata to perform DI, define AOP proxies and configure your application to run in a low-memory environment.

This is all from this Post, if you find anything incorrect or have different thoughts, please comment below in the comment box.

Complete Application Deployment using Kubernetes

Ishant Gaurav — Wed, 23 Jun 2021 05:11:24 +0000

In this post, we will be deploying a complete end to end application using Kubernetes. We will see and discuss how the different components of Kubernetes compliment each other and make the application deployment process smooth.

We will be using minikube to deploy our application on our local system. You can refer this link to read more about minikube : https://minikube.sigs.k8s.io/docs/start/

Once you are done with this post, you would be familiar with the below concepts in Kubernetes:

Creating Deployment using YAML file.
What is Pod and How to define the pod in YAML config file.
How to to create internal service and make the pod accessible to other component in the cluster.
How to create external service and make the pod accessible outside the cluster.

Sample application which we will be deploying on the Kubernetes cluster will be as below. We will deploy mongodb and mongo-express docker image and will access the mongo-express from the browser.

To deploy the above application on Kubernetes we will be following the below steps:

1.First we will create mongodb secret which will contain the sensitive information such as the mongodb username and password in encrypted format.

Then create mongodb deployment and service which will be responsible to create the mongdb pod and exposing the mongodb to the other internal components.
Now we will create mongodb configmap to save the mongodb url and other configuration.
Once config map is created and deployed we will create the mongo-express deployment file to create the mongo-express pod.
Accessing the application from the browser.

Before implementing the above steps to deploy the mongodb application on Kubernetes, lets revise the few Kubernetes components which will be used in deploying the application in brief.

Pods: Pods are the smallest, most basic deployable objects in Kubernetes. A Pod represents a single instance of a running process in your cluster. Pods contain one or more containers, such as Docker containers.

Secrets: Secrets let you store and manage sensitive information, such as passwords, OAuth tokens, and ssh keys. Storing confidential information in a Secret is safer and more flexible than putting it verbatim in a Pod definition or in a container image

ConfigMap: A ConfigMap is an API object used to store non-confidential data in key-value pairs. Pods can consume ConfigMaps as environment variables, command-line arguments, or as configuration files in a volume.A ConfigMap allows you to decouple environment-specific configuration from your container images, so that your applications are easily portable.

Deployment: Deployment is a resource object in Kubernetes that provides declarative updates to applications. A deployment allows you to describe an application’s life cycle, such as which images to use for the app, the number of pods there should be, and the way in which they should be updated.

Services : Service is a logical abstraction for a deployed group of pods in a cluster (which all perform the same function). Since pods are ephemeral, a service enables a group of pods, which provide specific functions (web services, image processing, etc.) to be assigned a name and unique IP address (clusterIP).

Note: ConfigMap does not provide secrecy or encryption. If the data you want to store are confidential, use a Secret rather than a ConfigMap, or use additional (third party) tools to keep your data private.

Now let’s deploy the complete mongodb application by following the steps discussed above. Architecture of our application with different components will be as below :

Step 1: Create Secrets to Save Mongodb username and password .

As our mongodb application require username and password to access, as username and password are confidential information, so will be creating the secrets to save them. We have username as “username” and password as “password“. We are saving them by encoding in base64.

mongo-secret.yaml

apiVersion: v1
kind: Secret
metadata:
    name: mongodb-secret
type: Opaque
data:
    mongo-root-username: dXNlcm5hbWU=
    mongo-root-password: cGFzc3dvcmQ=

apiVersion : this is the version of the API used by the cluster.

kind: kind define whether it’s a deployment, secret or configMap.

metadata: here we can define data about the object we are about to create. In this example, we only provide the name of the pod. But you can provide other details like the namespace.

type: type Opaque means that from kubernetes’s point of view the contents of this Secret is unstructured, it can contain arbitrary key-value pairs.

data : data contains the data, you want to save as secrets.

Deploy the secret config file via kubectl apply -f mongo-secret.yaml.

Step 2 : Create the mongo deployment and Service to create the mongo pod.

Now we will create the mongo deployment to create the mongodb pod, mongo db deployment will be fetching the mongodb username and password from the mongo secrets created in Step1.

mongo.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mongodb-deployment
  labels:
    app: mongodb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mongodb
  template:
    metadata:
      labels:
        app: mongodb
    spec:
      containers:
      - name: mongodb
        image: mongo
        ports:
        - containerPort: 27017
        env:
        - name: MONGO_INITDB_ROOT_USERNAME
          valueFrom:
            secretKeyRef:
              name: mongodb-secret
              key: mongo-root-username
        - name: MONGO_INITDB_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mongodb-secret
              key: mongo-root-password
---
apiVersion: v1
kind: Service
metadata:
  name: mongodb-service
spec:
  selector:
    app: mongodb
  ports:
    - protocol: TCP
      port: 27017
      targetPort: 27017

In the above yaml file we have defined two things :

1.Deployment – responsible to create the pod and replicaset of the pod.(here we are creating only one replica).
2.Service – to expose the pod to the internal component.

Now Let’s see the each field in deployment in the more details:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mongodb-deployment
  labels:
    app: mongodb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mongodb
  template:
    metadata:
      labels:
        app: mongodb
    spec:
      containers:
      - name: mongodb
        image: mongo
        ports:
        - containerPort: 27017
        env:
        - name: MONGO_INITDB_ROOT_USERNAME
          valueFrom:
            secretKeyRef:
              name: mongodb-secret
              key: mongo-root-username
        - name: MONGO_INITDB_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mongodb-secret
              key: mongo-root-password

apiVersion : this is the version of the API used by the cluster.

kind: kind define whether it’s a deployment, secret or configMap.

metadata: here we can define data about the object we are about to create. In this example, we only provide the name of the pod. But you can provide other details like the namespace.

spec: in the deployment kind file, we have spectification which is responsible for defining the replica, selector and container template.

replicas : define the number of pod to be created for this container.

selector: inside selector we define the matching Label.

template: template is the actual blue print of the container and pod that will be created.

template.metadata : contains the information about pod like label etc.

template.spec: blueprint for the container that needs to be created.

containers : define the different pod to be created.

name: name of container.

image: docker image that will be pulled from docker hub.

ports: on which this container will be accessible.

env : container the environment variables like mongodb username and password in our case.

Note: Secrets needs to be created first before the applying the deployment as they are being used in the deployment as environment variable.

Let’s see the service in more detail now:

apiVersion: v1
kind: Service
metadata:
  name: mongodb-service
spec:
  selector:
    app: mongodb
  ports:
    - protocol: TCP
      port: 27017
      targetPort: 27017

Service yaml has the similar fields as in the deployment, only targetPort field is different, targetPort is the port on which other component can access this pod.

Step 3: Create Secrets to Save Mongodb username and password

Now we will create the configMap which will contain the mongodb url.

mongo-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: mongodb-configmap
data:
  database_url: mongodb-service

ConfigMap file is almost similar to the other yaml file.

Step 4: Create the mongo-express deployment and external service to create the mongo-express pod and expose it to the outside of cluster.

mongo-express.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mongo-express
  labels:
    app: mongo-express
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mongo-express
  template:
    metadata:
      labels:
        app: mongo-express
    spec:
      containers:
      - name: mongo-express
        image: mongo-express
        ports:
        - containerPort: 8081
        env:
        - name: ME_CONFIG_MONGODB_ADMINUSERNAME
          valueFrom:
            secretKeyRef:
              name: mongodb-secret
              key: mongo-root-username
        - name: ME_CONFIG_MONGODB_ADMINPASSWORD
          valueFrom:
            secretKeyRef:
              name: mongodb-secret
              key: mongo-root-password
        - name: ME_CONFIG_MONGODB_SERVER
          valueFrom:
            configMapKeyRef:
              name: mongodb-configmap
              key: database_url
---
apiVersion: v1
kind: Service
metadata:
  name: mongo-express-service
spec:
  selector:
    app: mongo-express
  type: LoadBalancer  
  ports:
    - protocol: TCP
      port: 8081
      targetPort: 8081
      nodePort: 30000

mongo-express deployment config is similar to the mongodb deployment config so we will not discuss that here.

We will discuss few of the extra field that we have in the mongo-express external service below:

apiVersion: v1
kind: Service
metadata:
  name: mongo-express-service
spec:
  selector:
    app: mongo-express
  type: LoadBalancer  
  ports:
    - protocol: TCP
      port: 8081
      targetPort: 8081
      nodePort: 30000

This service file contains 2 fields extra (type, nodePort )as compared to the service file of mongodb.

type: LoadBalancer : makes the service external by assigning the service external ip address.

nodePort: port on which this pod can be accessed outside the cluster.

Step 5: Access the Mongo-Express from the browser.

To access the mongo-express from the browser, we would need to find the IP ADDRESS of the service assigned by the kubernetes.

We will first verify if the service is created and will fetch the service name by the following command

kubectl get service

As we can see our external service with the name mongo-express-service and internal service mongodb-service both have been created.

Now we will run our external service to get the url created for the service to be accessible by using below command.

minikube service mongo-express-service

Now copy paste the url in browser and check whether application is accessible.

We can see that we are able to access the application in our browser on port 30000 as given in the external service yaml file.

Conclusion

So in this way we deployed a complete end to end mongo db application on kubernetes and access it through our browser. We created a mongodb pod and made it accessible to the other component by internal service. We also created one pod for mongo-express to make changes to mongodb and created an external service to make it accessible outside the cluster or external source.

This is all from this Post, if you have any question or find anything wrong, then please comment below.

This post was first published on my personal blog. If you find this blog content relevant, you can visit my blog for similar kind of content: https://ishantgaurav.in/

Lazy Initialization in Java8

Ishant Gaurav — Sun, 13 Jun 2021 14:52:28 +0000

We don’t have any Lazy<T> initialisation functionality in Java as we have in other languages like Scala, C# etc. But don’t worry in Java we can implement the same kind of functionality by leveraging the Lambda’s and Functional interface.

In this example to create the lazy evaluation we will use the Supplier<T> interface, although same can be implemented by applying the other interface as well.

Let’s understand first, How Supplier<T> interface can be used to implement lazy initialisation.

Supplier<T> interface represents a function which does not take in any argument but produces a value of type T. Suppliers are useful when we don’t need to supply any value and obtain a result at the same time.

Definition of Supplier<T> interface is as below :

@FunctionalInterface
public interface Supplier<T> {

    /**
     * Gets a result.
     *
     * @return a result
     */
    T get();
}

Lambda code of Supplier<T> interface is only executed when we execute the get() method of Supplier interface.

If you create an object directly using the new operator, it eagerly creates the object where as if the same object is being created using the Supplier then it will be lazy initialisation as object will be created only when we call get() method of Supplier interface.

String name = "Ishant"; // eager

Supplier<String> v2 = () -> "Ishant"; // lazy

Let’s see the complete working example to understand it better.

package com.ishant.java8;

import java.util.function.Supplier;

class CustomObject {
    CustomObject (String value) {
        System.out.println(value);
    }

    public static CustomObject getObject(String value) {
        return new CustomObject(value);
    }
}

public class SupplierExample {

    public static void main(String[] args) {
        Supplier<CustomObject> customObjectSupplier = () -> CustomObject.getObject("Lazy initialization");
        CustomObject customObject = CustomObject.getObject("Eager initialisation");
        System.out.println("Supplier not called yet");
        customObjectSupplier.get();

    }
}

Output :

Supplier not called yet
Lazy initialization

In the above output, we can see that Lazy initialisation was printer after the Supplier<T> get() method was executed.

Memoization Issue

Problem : Issue with the above approach is that, every time Supplier get() method is called new instance of CustomObject will be created.

We can verify the same with below example.

package com.ishant.java8;

import java.util.function.Supplier;

class CustomObject {

    private static int value = 0;
    CustomObject () {
        value++;
        System.out.println("Value : " + value);
    }

    public static CustomObject getObject() {
        return new CustomObject();
    }
}

public class SupplierExample {

    public static void main(String[] args) {
        Supplier<CustomObject> customObjectSupplier = () -> CustomObject.getObject();
        customObjectSupplier.get();
        customObjectSupplier.get();
        customObjectSupplier.get();

    }
}

Output :

Value : 1
Value : 2
Value : 3

As in the output above we can see that the value have been printed thrice, which means that on every get() call a new instance of CustomObject is being created.

How to fix this the memoization issue ?

Due to the not memoizing the instance of class issue, we won’t be able to use this Lazy initialisation technique where we need to maintain the singleton property of a class. For that what we can do is we can create another Lazy class and that class hold both a Supplier<T> and the value T itself:

public class Lazy<T> implements Supplier<T> { 
    private final Supplier<T> supplier;
    private T value;

    @Override
    public T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

Let’s verify whether the above technique is maintaining the singleton property of a class or not as below :

package com.ishant.java8;

import java.util.function.Supplier;

class CustomObject {

    private static int value = 0;
    CustomObject () {
        value++;
        System.out.println("Value : " + value);
    }

    public static CustomObject getObject() {
        return new CustomObject();
    }
}

class Lazy<T> implements Supplier<T> {
    private final Supplier<T> supplier;
    private T value;

    Lazy(Supplier<T> supplier) {
     this.supplier = supplier;
    }

    @Override
    public T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

public class SupplierExample {

    public static void main(String[] args) {
        Lazy<CustomObject> customObjectSupplier = new Lazy(() -> CustomObject.getObject());
        System.out.println("Call  1 : " + customObjectSupplier.get());
        System.out.println("Call  2 : " + customObjectSupplier.get());
        System.out.println("Call  3 : " + customObjectSupplier.get());
    }
}

Output :

Value : 1
Call  1 : com.ishant.java8.CustomObject@566776ad
Call  2 : com.ishant.java8.CustomObject@566776ad
Call  3 : com.ishant.java8.CustomObject@566776ad

From the output, we can simply see that Value: 1 has been printed only once and on every call the hascode of the object is same.

Multithreading Issue :

We made a new class to lazily initialised the class and also maintained to create the only single instance of a class.

Problem : But in the above code singleton property of class won’t be applicable in multithreading environment as two threads might come to create the instance of class at the same time and both will be bound to create new instance, in that way multiple instance of class will be created .

Let’s verify the same with the below code :

package com.ishant.java8;

import java.util.function.Supplier;

class CustomObject {

    private static int value = 0;
    CustomObject () {
        value++;
        System.out.println("Value : " + value);
    }

    public static CustomObject getObject() {
        return new CustomObject();
    }
}

class Lazy<T> implements Supplier<T> {
    private final Supplier<T> supplier;
    private  T value;

    Lazy(Supplier<T> supplier) {
     this.supplier = supplier;
    }

    @Override
    public T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

public class SupplierExample {

    public static void main(String[] args) {
        Lazy<CustomObject> customObjectSupplier = new Lazy(() -> CustomObject.getObject());

        Runnable runnable =  () -> customObjectSupplier.get();

        Thread thread1 = new Thread(runnable);
        Thread thread2 = new Thread(runnable);
        Thread thread3 = new Thread(runnable);
        Thread thread4 = new Thread(runnable);

        thread1.start();
        thread2.start();
        thread3.start();
        thread4.start();
    }
}

Output :

Value : 3
Value : 3
Value : 4
Value : 3

As per the code output above, we can verify that value:3 and value:4 has been printed which means that multiple instance of same object has been created.

How to fix the multithreading issue ?

To fix the multithreading issue, we can simply make the get() method synchronised so that multiple thread can’t access the same get() at the same time. Also we can make the value property as volatile so that its value is write and read form the main memory only and not from the CPU cache.

Note : We can also implement the double check locking using synchronised block to make the code more proficient but to keep the simplicity for this code, i am just making the whole method synchronised.

Let’s see the code for above :

class Lazy<T> implements Supplier<T> {
    private final Supplier<T> supplier;
    private volatile T value;

    Lazy(Supplier<T> supplier) {
     this.supplier = supplier;
    }

    @Override
    public synchronized T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

Let’s see the complete example and verify above code :

package com.ishant.java8;

import java.util.function.Supplier;

class CustomObject {

    private static int value = 0;
    CustomObject () {
        value++;
        System.out.println("Value : " + value);
    }

    public static CustomObject getObject() {
        return new CustomObject();
    }
}

class Lazy<T> implements Supplier<T> {
    private final Supplier<T> supplier;
    private  volatile T value;

    Lazy(Supplier<T> supplier) {
     this.supplier = supplier;
    }

    @Override
    public synchronized T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

public class SupplierExample {

    public static void main(String[] args) {
        Lazy<CustomObject> customObjectSupplier = new Lazy(() -> CustomObject.getObject());

        Runnable runnable =  () -> customObjectSupplier.get();

        Thread thread1 = new Thread(runnable);
        Thread thread2 = new Thread(runnable);
        Thread thread3 = new Thread(runnable);
        Thread thread4 = new Thread(runnable);

        thread1.start();
        thread2.start();
        thread3.start();
        thread4.start();
    }
}

Output :

Value : 1

Output of the above code signify that only one instance has been created.

Final Code for Lazy Implementation :

class Lazy<T> implements Supplier<T> {
    private final Supplier<T> supplier;
    private  volatile T value;

    Lazy(Supplier<T> supplier) {
     this.supplier = supplier;
    }

    @Override
    public synchronized T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

This Post was first published on my Personal blog website. If you like this post relevant, you cam further read other Post from there : https://ishantgaurav.in/

This is all from this Post, if you find anything wrong or have any other thoughts on the same , please share in the comment box below :

Microservice Pattern : API Gateway

Ishant Gaurav — Mon, 31 May 2021 17:49:45 +0000

When we talk about the system design or see those big Mircoservice Architecture diagram, there is a component with name api-gateway which always comes into the picture. In this blog we will see what exactly is the API gateway and why do we need it, when and where to use it.

Before reading this post or learning about the api-gateway, i would suggest you to learn about proxy and reverse-proxy first or go through my other blog in which i have shared the information about the same.

Ok, now lets start with the definition of api-gateway

"API gateway is a tool that sits between the client and the collection of backened services. An API gateway acts as a reverse proxy to accept all api calls, aggregate the various services required to fulfill them, and return the appropriate result."

Let's understand the problem we would face if we don't use the API gateway. Let's take a scenario of an basic ecommerce website which has microservice architecture as below:

Customer Service : handles the new customer addition, updation, deletion etc.
Product Service: gives all the information about the products.
Inventory Service: takes care of all the quantity or availability of products.
Order Service : handles payment and place the order.

As we have microservice architecture having more than one service for front-end to interact with, it would lead to below problems :

Front-end itself has to play the role of API-Composer, it fetches the result from different services and combine the result.
Front end will have to call all the each service separately, which mean there will be 4 network calls, which could cause performance issue to the application.
We would have to implement authorization/authentication mechanism for all the service separately for each individual call from front end to backend.
We are not able to implement common caching mechanism.
All the service will have to follow communication protocol like REST/HTTP as client is directly communicating to services.
From Security point of view, will have to implement HTTPS with all the service.

Now let's see how an api-gateway can overcome all the above problems for us and what other benefits it provides and come out as an essential component in microservices architecture.

The main responsibility of api-gateway is to route the request to the required service, perform protocol transformation and combined the results from different services into one.

Apart from the main functionality api-gateway provides a lot of another benefits as well :

Caching : Response from the services can be cached in api-gateway to prevent network call.
Authorization/Authentication : Instead of verifying the identity of the client and authentication at each service, it can be implemented in api-gateway.
Less Network calls : As we can see now the client will have to make one only network call to api-gateway and further call to services will be executed by the api-gateway only which are in same network, hence it will enhance the performance a lot.
Different protocol: Now the backend service can be implemented in different protocol like REST/HTTP and gRPC and not just client friendly protocol as HTTP and WebSocket.
Rate Limiting : Limiting how many requests per second from either a specific client and/or from all clients.
Metrics collection: Collect metrics on API usage for billing analytics purposes.
Request logging: Log requests to different services which can help later on in debugging.
Easy to add another service : Now we can easily add another service in the backend without client being aware of that.

Drawback of using API-Gateway :

In the microservice architecture, it becomes the one highly available component which needs to be developed, deployed and managed carefully.
Add more complexity to the application architecture.

This blog was first posted on my blog as https://ishantgaurav131.wordpress.com/. If you find this blog relevant, you can visit my blog for more such content.

This is all from this Post. Thanks for reading, and let me know your thoughts in the comments!