DEV Community: Gokul G.K.

Design pattern visualization: Structural Design Patterns

Gokul G.K. — Sun, 15 Mar 2026 16:09:32 +0000

Refactoring Guru already has the best blog to learn Design patterns. Here I am just trying to give a brief about each design.

Design patterns are solutions to recurring problems and design paradigms.

Structural design patterns describe how to combine objects and classes into larger structures while maintaining flexibility and efficiency.

You can get the Java code here or some detailed examples.

Let's dive into each one.......

Adapter

An adapter is a design pattern that allows objects with incompatible interfaces to work together effectively.

Rather than a rail-to-car adaptor (which sounds like AI-generated, which it isn't), a universal power adaptor is the best real-world example.

Class Diagram

The Adapter pattern acts as a bridge between two incompatible interfaces. Just like a physical travel adapter allows a European plug to work in a US wall outlet, the software Adapter allows classes with mismatched interfaces to work together smoothly.

Client: The class that wants to interact with a system using a specific, expected interface (the Target).
Target: The interface or abstract class that the Client understands and expects to work with. It defines the standard request() method.
Adaptee: The existing, already-built class that contains the functionality the Client needs, but it has an incompatible interface (like specificRequest()).
Adapter: The bridge class. It implements the Target interface so the Client can use it, but under the hood, it holds a reference to the Adaptee and translates the request() method into the specificRequest() method the Adaptee understands.

Bridge

A bridge is a design pattern that allows separating a large class or a set of related classes into two distinct hierarchies: abstraction and implementation, which can be developed independently.

Class Diagram

The Bridge pattern separates a class's interface (its abstraction) from its implementation, allowing both to be modified independently without breaking client code. This is particularly useful for preventing a "Cartesian product" explosion of classes (for example, instead of creating RedCircle, BlueCircle, RedSquare, and BlueSquare, create a Shape abstraction that holds a bridge to a Color implementor).

Client: The code that uses the system. It only interacts with the Abstraction and doesn't need to know anything about the underlying implementations.
Abstraction: The high-level control layer. It defines the basic interface for the client and maintains a reference to an Implementor object. It delegates the actual work to this implementor.
RefinedAbstraction: A specific variant or extension of the Abstraction. It implements the specific behaviors of the high-level entity (e.g., a Circle or Square class extending a general Shape class).
Implementor: The interface for all implementation classes. It doesn't have to match the Abstraction's interface at all; typically, the Implementor provides primitive operations, while the Abstraction defines higher-level operations based on those primitives.
ConcreteImplementor (A/B): The specific, concrete classes that carry out the actual work (e.g., the Red or Blue color classes).

Composite

Composite is a structural design pattern that allows you to combine objects into tree structures and treat them as individual entities.

Class Diagram

The Composite pattern is used to represent part-whole hierarchies as tree structures. Its primary superpower is that it allows the client code to treat individual objects (leaves) and compositions of objects (branches/nodes) in the exact same way. Think of a file system: a folder (Composite) and a file (Leaf) can both be moved, deleted, or renamed (Component operations), even though a folder contains other files and folders.

Client: The code that interacts with the objects in the tree structure. It uses the Component interface, meaning it doesn't need to check whether it's dealing with a single object or a complex group.
Component: The base interface or abstract class for all objects in the composition. It defines common operations (such as operation()) and usually includes methods for adding, removing, or accessing child components.
Leaf: The basic, building-block object that has no children. It implements the Component interface and defines the behavior of the operation() method. In a file system, this is the individual file.
Composite: The complex object that contains child components (which can be Leaves or other Composites). It implements the Component interface. When operation() is called on a Composite, it typically iterates over its children and delegates the work to them.

Decorator

A decorator is a design pattern that allows you to attach new behaviors to objects by placing them inside special wrapper objects that include those behaviors.

Class Diagram

The Decorator pattern allows you to attach new behaviors or responsibilities to an object dynamically at runtime, without altering its structure or relying on massive subclassing. Think of it like ordering a plain coffee and then adding "decorations" like milk, sugar, and caramel—each addition wraps the original object and adds its own flavor, but it is still fundamentally a coffee.

Client: The code that interacts with objects through the standard Component interface. It doesn't need to know whether it is working with a plain ConcreteComponent or one wrapped in multiple decorators.
Component: The common interface or abstract class for both the core objects and the decorators. It defines the standard methods (like operation()) that can be used or overridden.
ConcreteComponent: The base, standalone object to which new behaviors can be added. It implements the basic behavior defined in the Component interface (e.g., the plain black coffee).
Decorator: An abstract class that implements the Component interface and simultaneously contains a reference (or wrapper) to a Component object. Its primary job is to delegate all requests to the wrapped component by default.
ConcreteDecorator (A/B): The classes that extend the base Decorator to add new, specific behaviors or state. They override the operation() method to execute their custom code either before or after delegating the rest of the work to the wrapped component.

Facade

A facade is a design pattern that provides a simplified interface to complex libraries, frameworks, or classes.

Class Diagram

The Facade pattern provides a simplified, unified interface to a complex set of underlying subsystems. Think of it like a smart home hub: instead of having to manually turn on the lights, roll down the blinds, and turn on the TV with three different remotes, the hub gives you a single "Movie Mode" button (the Facade) that handles all the complex underlying interactions for you.

Client: The code that needs to interact with the complex subsystem. Instead of managing dozens of individual subsystem classes, it simply calls the easy-to-use methods provided by the Facade.
Facade: The "front-facing" class that provides the simplified interface. It knows exactly which subsystem classes are responsible for a request and delegates the client's command to the appropriate places in the correct order.
Subsystem Classes (A/B/C): The complex, underlying classes that do the actual, heavy-lifting work. They handle the specific tasks assigned by the Facade. Importantly, these classes operate independently and have no knowledge that the Facade exists—they don't hold references back to it.

Flyweight

A flyweight is a design pattern that allows you to fit more objects into available RAM by sharing common parts of their state among multiple objects rather than storing all data in each one.

Class Diagram

The Flyweight pattern is all about memory optimization. It allows you to fit more objects into the available RAM by sharing common parts of state across multiple objects, rather than keeping all the data in each individual object. Think of a word processor: instead of creating a brand new object for every single letter "e" in a document (which would eat up memory), the system creates exactly one "e" object that holds the font shape (the shared, unchanging data). The exact coordinates on the page where that "e" appears (the unique, changing data) are passed in from the outside.

Client: The code that uses the flyweights. It calculates or stores the "extrinsic" state (the unique context, like the coordinates of a letter on a page) and passes it to the flyweight's methods when needed.
FlyweightFactory: A manager class that creates and maintains a pool of flyweight objects. When a client requests a flyweight, the factory checks if one already exists. If it does, it returns the existing instance; if not, it creates a new one, adds it to the pool, and returns it.
Flyweight: The interface or abstract class that defines how flyweights can receive and act on extrinsic state passed in by the client.
ConcreteFlyweight: The object that implements the Flyweight interface and stores the "intrinsic" state. This state must be immutable (unchanging) and shared across all contexts.
UnsharedConcreteFlyweight: The pattern allows for flyweights that aren't actually shared. Sometimes you have an object that implements the Flyweight interface so it can be treated uniformly by the client, but it maintains all of its own state internally rather than sharing it.

Proxy

A proxy is a design pattern that allows you to create a substitute or placeholder for another object. It manages access to the original object, enabling you to perform an operation before or after the request is sent to it.

Class Diagram

The Proxy pattern provides a surrogate or placeholder for another object, allowing it to control access to that object. While it looks structurally very similar to the Decorator or Adapter patterns, its intent is different: an Adapter changes the interface, a Decorator adds behavior, but a Proxy controls access. Think of a company credit card: it acts as a proxy for the company's bank account. Both the card and the account share the same "payment" interface, but the card controls access, perhaps imposing limits or logging transactions before interacting with the actual funds.

Client: The code that needs to use the real object. Because it interacts strictly with the Subject interface, it doesn't know (and doesn't need to know) whether it is talking to the RealSubject or the Proxy.
Subject: The common interface shared by both the RealSubject and the Proxy. This ensures the proxy can be used interchangeably anywhere the real object is expected.
RealSubject: The actual, underlying object that contains the real business logic or heavy resource. It actually handles the work when the proxy finally passes the request along.
Proxy: The middleman. It implements the Subject interface and holds a reference to the RealSubject. When the client makes a request, the proxy intercepts it. It might check access permissions, log the request, handle lazy loading (delaying the creation of a heavy' RealSubject' until it is absolutely needed), and ultimately delegate the work to the RealSubject.

Structural Design Patterns: Real-World & Technical Examples

Design Pattern	What it does (The "TL;DR")	Real-World Analogy	Technical Application
Adapter	Acts as a bridge between two incompatible interfaces, allowing them to work together.	A travel plug adapter that allows a US laptop charger to fit into a European wall outlet.	Wrapping a legacy XML-based billing API so it can be used by a modern JSON-based microservice.
Bridge	Separates an abstraction (interface) from its implementation, allowing the two to vary independently.	A universal remote (abstraction) that can be paired with different TV brands (implementations).	A UI framework where a Button abstraction delegates its rendering to underlying OS-specific (Windows/macOS) implementations.
Composite	Composes objects into tree structures to represent part-whole hierarchies, treating individual objects and groups uniformly.	A shipping box that contains individual products as well as smaller boxes, which in turn contain more products.	A file system where both Directory and File share a common interface for operations like getSize() or delete().
Decorator	Dynamically attaches new responsibilities or behaviors to an object without altering its underlying structure.	Ordering a basic coffee and adding "decorators" like milk, caramel syrup, and whipped cream.	Wrapping a base FileDataReader with a CompressionDecorator and an EncryptionDecorator before saving to a database.
Facade	Provides a simplified, higher-level interface to a complex subsystem of classes.	A smart home hub's "Movie Mode" button automatically dims lights, closes blinds, and turns on the TV.	A simple VideoConverter class that hides the complex interactions of underlying audio/video codec libraries and buffer management.
Flyweight	Minimizes memory usage by sharing as much data as possible with similar objects, rather than keeping all data in each object.	Using a single master blueprint to build a massive neighborhood of structurally identical houses.	A text editor that loads a single instance of a character glyph (like the letter "e") into memory and reuses it, only passing its unique X/Y coordinates on the screen.
Proxy	Provides a surrogate or placeholder to control access to the original object.	A credit card acting as a proxy for your bank account—it controls access to your funds and enforces limits.	A LazyImageLoader that displays a lightweight placeholder icon on a webpage until the user scrolls down, at which point it loads the heavy, high-res image.

Design pattern visualization: Creational Design Patterns

Gokul G.K. — Wed, 18 Feb 2026 02:33:06 +0000

Refactoring Guru already has the best blog to learn Design patterns. Here I am just trying to give a brief about each design.

Design patterns are solutions to recurring problems and design paradigms.

Creational design patterns provide various mechanisms for object creation, increasing flexibility and the reuse of existing code.

We have around 5 patterns. You can get the Java code here, hope it works, built a couple of years back

Let's dive into each one.......

Factory Method

Factory Method is a design pattern that provides an interface for creating objects in a superclass while allowing subclasses to modify the types of objects that are created.

Imagine a pizza shop where you can order different types of pizza, but the creation process (baking, adding toppings) is handled by specific pizza factories(which I am not sure) for each type.

Another example that makes sense is different types of factories for other kinds of cars.

Let's see a class diagram for the Factory class.

Quick Explanation of the Diagram

Product (Interface): Defines the interface of objects that the factory method creates.
ConcreteProduct: The actual implementation of the Product.
Creator (Abstract Class): Declares the factory method (createProduct). It can also contain core business logic that relies on the Product objects.
ConcreteCreator: Overrides the factory method to return an instance of a ConcreteProduct.

Abstract Factory Method

Abstract Factory is a design pattern that enables the creation of families of related objects without specifying their concrete classes.

Abstract Factory is a factory of factories, where you build a factory class from Abstract Factory, which in turn builds the type of class you need.

Let's check out the Abstract Factory class diagram. You can clearly see the difference between the factory class and why the abstract factory pattern is Factory of Factories.

Quick Explanation of the Diagram

Abstract Factory (Interface): Declares a set of methods for creating each of the abstract products (e.g., createProductA, createProductB).
Concrete Factory: Implements the creation methods to produce a specific flavor or family of products (e.g., ConcreteFactory1 only creates ProductA1 and ProductB1).
Abstract Product (Interface): Defines the interface for a type of product (e.g., ProductA), ensuring all variations of that product are compatible.
Concrete Product: The specific implementation of a product type, created by the corresponding concrete factory to ensure they match other products in the same family.

Singleton

Singleton is a design pattern that guarantees a class has only one instance while providing a global access point to this instance.

Imagine a single barista/coffee machine, the single instance, that makes all kinds of coffee.

A Singleton class will have a single instance.

Quick Explanation of the Diagram

Singleton Class: The single class responsible for creating and managing its own unique instance.
instance (Private Static Variable): A static member that holds the only instance of the class. The $ symbol (or the underline in standard UML) denotes a static member.
Singleton() (Private Constructor): A constructor with private visibility that prevents other objects from using the new operator with this class.
getInstance() (Public Static Method): The global access point. When called, it checks if the instance is null; if so, it creates one. It then returns that same instance to every caller.

Prototype

Prototype is a creational design pattern that allows you to copy existing objects without making your code dependent on their classes.

Consider a cloning Machine, which is a good example of a prototype.

Let's check the UML Diagram.

Quick Explanation of the Diagram

Prototype (Interface): Declares the interface for cloning itself, usually consisting of a single clone method.
Concrete Prototype: Implements the cloning operation by copying its own data into a new object instance.
Client: Creates new objects by asking an existing prototype instance to clone itself instead of instantiating a class from scratch.

Builder

The Builder design pattern allows you to construct complex objects step by step. This pattern enables the production of different types and representations of an object using the same construction code.

You travelled to 2050. Now you get a burger-building machine kiosk, which builds it step by step.

Visualization for Builder.

Quick Explanation of the Diagram

Director: Defines the order in which to execute the building steps. It works with a builder object to create a specific product configuration (e.g., a "Vegan Burger" vs. a "Double Cheeseburger").
Builder (Interface): Declares all possible steps required to build a product. These steps are common to all types of builders.
Concrete Builder: Provides a specific implementation of the building steps. It is responsible for creating and assembling the parts of the complex object and returning the final product.
Product: The resulting complex object. Unlike other creational patterns, different builders can produce products that do not follow a common interface (e.g., a "House" product vs. a "Manual" product).

Creational Design Patterns Overview

Design Pattern	Description	Other Example
Factory Method	Subclasses decide object type	`PizzaStore` with regional pizza creators (`NYPizzaStore`, `ChicagoPizzaStore`)
Abstract Factory	Creates related object families	`GUIFactory` for Windows/Mac button + checkbox pairs
Singleton	One instance, global access	Single `Logger` or `DatabaseConnectionPool` across app
Prototype	Clone objects without class dependency	Duplicate `Circle`/`Rectangle` shapes via `clone()` method
Builder	Step-by-step complex object construction	`HouseBuilder` for `WoodenHouse` or `StoneHouse` variants

API designs for microservice comparison.

Gokul G.K. — Thu, 05 Feb 2026 22:17:24 +0000

I have created a separate blog for REST, GraphQL, and gRPC.
The codebase for Imaginary Aquarium retail, implemented across all three APIs, can be found here.

I tried to include images and tables for comparison.

1. High-Level Architectural Comparison

Aspect	REST	GraphQL	gRPC
Core Style	Resource-oriented	Query language with a schema	Remote Procedure Calls
Transport	HTTP/1.1 (mostly)	HTTP/1.1 or HTTP/2	HTTP/2
Data Format	JSON (XML optional)	JSON	Protocol Buffers (binary)
Endpoints	Multiple URL endpoints	Single endpoint (`/graphql`)	Method names within services
Typing/Schema	Weak typing	Strongly typed schema	Strongly typed via `.proto`
Tooling & Ecosystem	Very mature	Growing fast	Strong, but narrower scope
Typical Use Cases	Public APIs, simple CRUD	Flexible client-driven data needs	High-performance microservices

2. Performance & Efficiency

Metric	REST	GraphQL	gRPC
Latency	Moderate	Variable (depends on query complexity)	Very low
Throughput	Moderate	Depends (higher with precise queries)	Highest
Payload Size	JSON (often larger)	Depends on query	Small (binary)
Over-fetching Risk	High	Minimal (client defines data)	Low (compact payloads)
Streaming Support	HTTP streaming possible	Subscriptions (via WebSockets)	Built-in streaming

3. Developer Experience & Tooling

4. Security & Caching

Security & Caching	REST	GraphQL	gRPC
Authentication	OAuth2, JWT, API keys	JWT tokens, directive-based auth	TLS/mTLS, ALTS
Authorization	Role-based	Field-level controls possible	Interceptor-based
Caching	Native HTTP caching	Custom strategies required	Custom
Common Risks	Standard HTTP threats	Query complexity & DoS	Binary payload complexity

5. Versioning & Evolution

Versioning Strategy	REST	GraphQL	gRPC
Versioning	URL/version headers	Schema evolution & deprecation	Proto backward-compatible changes
Breaking Changes	Explicit version bump	Avoid by deprecation	Avoid by compat proto rules
Schema Contract	Implicit	Defined via GraphQL schema	Defined via `.proto`

Implementing gRPC.

Gokul G.K. — Thu, 05 Feb 2026 22:06:46 +0000

gRPC is a framework developed by Google that provides an efficient, language-independent mechanism for making Remote Procedure Calls (RPCs). Its primary use case is to enhance the performance of these remote calls while maintaining compatibility across different programming languages. Remote procedure calls are crucial in microservices and distributed environments, where large volumes of data are transferred between services.

Core Principle

gRPC is built on several core principles that contribute to its performance and capabilities:

Protocol Buffers: gRPC employs Protocol Buffers for serialization, allowing efficient binary encoding of data. This reduces message size and minimizes the parsing and serialization overhead, resulting in faster communication.
Strongly-typed contracts: gRPC APIs rely on strongly-typed contracts defined with Protocol Buffers that specify the services, methods, and data types available. This establishes a straightforward, consistent interface between the client and the server, minimizing the risk of errors and misunderstandings.
Bi-directional streaming: gRPC facilitates bi-directional streaming, allowing clients and servers to exchange messages simultaneously. This feature enhances communication efficiency, particularly for large or real-time data transfers.
Language-agnostic: gRPC is intended to be language-agnostic, offering official support for various programming languages such as C++, Java, Python, and Go. This flexibility allows developers to select the most appropriate language for their project without facing compatibility issues.

High-performance applications
Microservices architecture
Applications that require high scalability

gRPC is an excellent choice for performance-centric, scalable APIs in distributed systems, microservices, and real-time applications. It supports multiple languages and platforms with efficient binary data. It's ding. It's ideal for teams experienced in low-level programming and network communication, enabling fast, reliable APIs.

gRPC vs REST API: Comparison Table

Aspect	gRPC	REST
Protocol	HTTP/2	HTTP/1.1 (or HTTP/2)
Message Format	Protocol Buffers (Binary)	JSON, XML (Text)
Performance	⚡ Faster (binary serialization)	Slower (text parsing)
Payload Size	Smaller (~3-10x)	Larger
Latency	Lower	Higher
Bandwidth Usage	Lower	Higher
Code Generation	Automatic (from .proto files)	Manual or template-based
Browser Support	Limited (gRPC-Web required)	Native support
API Style	RPC (function calls)	Resource-oriented (URIs)
URL Routing	Service.Method	RESTful paths (/resource/id)
HTTP Methods	Uses POST for all	GET, POST, PUT, DELETE, PATCH
Caching	Difficult (custom logic)	Built-in (HTTP caching)
Streaming	Bidirectional streaming	Request-response only
Connection	Persistent (multiplexed)	Per-request
Learning Curve	Steeper	Easier
Ecosystem	Growing	Mature & established
Documentation	Code-generated (proto)	Manual documentation
Debugging	Harder (binary format)	Easier (JSON readable)
Mobile Friendly	Good	Very good
IoT/Edge Computing	Excellent	Good
Real-time Features	Excellent (streaming)	Limited
Interceptors/Middleware	Built-in	Manual implementation
Error Handling	Standardized (gRPC codes)	HTTP status codes
Authentication	JWT, OAuth, Certificates	OAuth, API Keys, JWT
Use Cases	Microservices, Real-time, Mobile	Public APIs, Web services

Java Implementation

Clone this Git repo.

Run these commands to build and run the applications
mvn clean install
mvn spring-boot:run

Expected outcome

🐠 ==========================================
🐠 AquaWorld Pet Store gRPC API
🐠 ==========================================
🐠 gRPC Server started on port 9090
🐠 Test with grpcurl: grpcurl -plaintext localhost:9090 list
🐠 ==========================================

Test Application
install grpcurl
grpcurl - Command-line tool for testing gRPC APIs

# macOS
brew install grpcurl

# Linux (requires Go)
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

Expected Result

com.aquaworld.grpc.auth.AuthService
com.aquaworld.grpc.order.OrderService
com.aquaworld.grpc.payment.PaymentService
com.aquaworld.grpc.product.ProductService
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection

Follow the ReadMe file to test the remaining functionalities.

gRPC Design and Best Practices

API Versioning in gRPC

Versioning via Proto Packages The recommended approach is to version your API using the package name in your .proto files.
Field Numbers Are Sacred In Protocol Buffers, field numbers must never be reused.
Don't Delete Instead of removing fields, mark them as deprecated.

Error Handling in gRPC

Use gRPC Status Codes Correctly
- OK – Success
- INVALID_ARGUMENT – Client sent invalid data
- NOT_FOUND– Resource does not exist
- ALREADY_EXISTS – Duplicate resource
- PERMISSION_DENIED – Authorization failure
- UNAVAILABLE – Service temporarily unavailable Avoid returning UNKNOWN or INTERNAL for client-side errors.
Rich Error Details via Trailers gRPC offers rich error metadata, enabling clients to handle failures programmatically through structured error details in trailers.

Deadlines, Timeouts, Retries, and Load Balancing

Always Set Deadlines A gRPC deadline defines how long a client is willing to wait for a response.
Retries Must Be Intentional Retries can improve resilience—but only when used carefully.
Load Balancing Considerations HTTP2'sssHTTP/2'ss long-lived connections, which change how load balancing works.

Choose gRPC if you need:

High performance and low latency
Efficient mobile/IoT communication
Real-time bidirectional streaming
Microservices architecture
Internal APIs between services
Minimal bandwidth usage

GraphQL for Beginners

Gokul G.K. — Tue, 27 Jan 2026 19:45:46 +0000

Why GraphQL Emerged: Solving the Pain Points of REST APIs

APIs are the backbone of how applications communicate and exchange data. REST has been the go-to architectural style for building APIs (at least for me). It's straightforward, relying on standard HTTP methods, with endpoints structured around resources (e.g., /users/123 to fetch a specific user). As applications grew more complex, think mobile apps, single-page web apps, and microservices, REST started showing its limitations.

The Over-Fetching and Under-Fetching Problems in REST

One of the biggest headaches with REST is overfetching and underfetching of data.
Overfetching happens when an API endpoint returns more data than the client actually needs.
Imagine a social media app that displays only a user's name and profile picture could use a REST endpoint like /users/123 to return only the relevant data. Returning the entire user object, including unnecessary details, wastes bandwidth and slows performance, especially on mobile devices.
On the other side, underfetching occurs when a single endpoint doesn't provide enough data, requiring the client to make multiple API calls.

GraphQL flips this script by empowering clients to specify precisely which data they need in a single request. Instead of rigid endpoints, clients send a query that looks like this:

query {
  products {
    id
    name
    category
    price
  }
}

The server responds with that exact structure, reducing network overhead, minimizing round-trip times, and speeding up development by preventing frontend teams from being blocked by backend changes.

Feature	Description
Strongly Typed	Complete type system defined in schema
Declarative	Client specifies what data is needed
Single Endpoint	All requests go to `/graphql`
Efficient	No over-fetching or under-fetching
Self-Documenting	Schema is the API documentation
Developer-Friendly	Built-in playground (GraphiQL)

GraphQL as a Query Language and Schema-Based Runtime

GraphQL is both a query language for your data and a runtime that executes queries based on a defined schema, which describes available data types, their relationships, and how to query them. It's usually written in Schema Definition Language (SDL), like:

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}
type Post {
  title: String!
  content: String
}
type Query {
  user(id: ID!): User
}

This schema is accessed through a single HTTP endpoint (usually /graphql), unlike REST's multiple URLs. Clients POST their queries to this endpoint, which validates them against the schema for type safety and rejects invalid requests. While transport-agnostic, it typically uses HTTP for easy integration with existing systems.

Core GraphQL Concepts: Building Blocks for Powerful APIs

The Schema: Types, Queries, Mutations, and Strong Typing.

The schema is the foundation of any GraphQL API. It's a blueprint that defines:

Types: These describe your data models. Scalar types (e.g., String, Int, Boolean) are built-in, while object types (like User or Post) are custom. You can define enums, interfaces, unions, and input types for added complexity.
Queries: The entry points for reading data. Think of them as read-only operations. The Query type in the schema lists available queries, like user(id: ID!), which returns a User object.
Mutations: For writing data, such as creating, updating, or deleting. Similar to queries but side-effecting.

GraphQL enforces strong typing for every field, allowing runtime checks against defined types. This catches errors early, avoiding issues like receiving a string instead of a number. In contrast, REST often uses loosely typed JSON, which can lead to fragile client code.

Operations: Queries, Mutations, and Subscriptions

GraphQL supports three main operation types:

Queries: For fetching data. They're idempotent (safe to retry) and can include arguments, fragments (reusable query parts), and variables for dynamic inputs.
Mutations: For modifying data. They follow the same structure as queries but signal changes.
Subscriptions: For real-time updates. Unlike queries and mutations (which are request-response), subscriptions use WebSockets to push data from server to client when events occur, like new messages in a chat app. A subscription might be subscription { newMessage(chatId: ID!): Message }, keeping the client in sync without polling.

Resolvers: The Data-Fetching Glue

Behind every field in a query or mutation is a resolver, a function that knows how to fetch or compute the data for that field. Resolvers are like mini-handlers, executed in a tree-like fashion as the query resolves from root to leaves.
In GraphQL, the root resolver fetches a user, while child resolvers retrieve related posts. This modular design allows data to be pulled from various sources, unlike REST controllers, which handle entire responses at once, leading to monolithic code. Resolvers enhance separation of concerns, enabling independent optimization and security for each field.

Java Code Example.

Let's convert the REST example for project Aquaworld to GraphQL.

REST vs GraphQL

AquaWorld Endpoint Comparison

Operation	REST	GraphQL
Get all products	`GET /api/v1/products`	`query { products { ... } }`
Get single product	`GET /api/v1/products/2001`	`query { product(id: 2001) { ... } }`
Create order	`POST /api/v1/orders`	`mutation { createOrder(input: {...}) { ... } }`
Get order with items	2 requests	1 request with nested data
Filter by name	`GET /api/v1/products/search?name=...`	`query { searchProducts(name: "...") { ... } }`

Data Fetching Comparison

REST: Fixed response structure (over-fetching)

GET /api/v1/products/2001
{
  "id": 2001,
  "name": "Red Guppy Male",
  "category": "guppies",
  "description": "...",
  "price": 5.99,
  "stock": 25,
  "imageUrl": "...",
  "createdAt": "2025-01-15"
}

GraphQL: Client specifies needed fields

query {
  product(id: 2001) {
    name
    price
    stock
  }
}
# Returns ONLY: name, price, stock

Quick Start Guide

Pull code from the API Architecture Repo

# 1. Navigate to the project.
cd /Users/gokulg.k/Documents/GitHub/API_Architecture/GraphQL/aquaworld-graphql-api

# 2. Build
mvn clean install

# 3. Run
mvn spring-boot:run

Check out the complete documentation for building the project from scratch, the API schema, the Visual Guide, and more.

GraphQL Endpoint

Query & Mutation: http://localhost:8080/aquaworld/graphql
Interactive Playground: http://localhost:8080/aquaworld/graphiql

Make Use of the GraphQL playground to test all queries.

Note: All the magic happens inside the resolver with the help of some annotations.

GraphQL Annotations in Spring Boot (`spring-graphql`)

Annotation	Description / When to Use
`@Controller`	Marks the class as a GraphQL controller (same annotation as in Spring MVC/REST, but used here for GraphQL resolvers)
`@QueryMapping`	Maps the method to a field in the root `Query` type — used for top-level read/fetch operations
`@MutationMapping`	Maps the method to a field in the root `Mutation` type — used for top-level create/update/delete operations
`@SubscriptionMapping`	Maps the method to a field in the root `Subscription` type — used for real-time updates (WebSocket-based)
`@SchemaMapping`	Most flexible mapping — connects the method to any field in the schema (root-level or nested object fields)
`@BatchMapping`	Batch-loads related data for multiple parent objects at once — prevents N+1 query problem in lists/relationships
`@Argument`	Explicitly binds a GraphQL argument to a method parameter (optional when parameter name matches the argument name)

GraphQL Design and Best Practices: Building APIs That Age Gracefully

GraphQL’s flexibility is powerful, but without discipline, it can lead to bloated schemas, performance nightmares, and maintenance headaches. The following best practices help create client-centric, stable, and performant GraphQL APIs that evolve smoothly over time.

Keep the Schema Client-Centric and Stable – Evolve by Addition, Not Replacement One of GraphQL’s biggest promises is that clients dictate the shape of the data, not the server.
- Design from the UI/use-case perspective
- Avoid breaking changes at all costs
- Evolve by addition instead of versioning the whole API
Use Pagination Patterns (Connections / Cursors) to Avoid Huge Responses GraphQL makes it dangerously easy to write queries that return thousands of items (e.g., products { id name price }). Without limits, this kills performance and can even DDoS your own server. Best practice: Always paginate lists using the Relay-style Connections pattern.
Handle Errors Gracefully Using the errors Field + Custom Extensions Unlike REST (where HTTP status + body tells the story), GraphQL always returns 200 OK if the query is syntactically valid—even if business logic fails. All errors live in the top-level errors array. Best practice: Structured, machine-readable errors.

Getting started with the REST API in Spring Boot.

Gokul G.K. — Tue, 20 Jan 2026 07:02:59 +0000

What is REST?

Representational state transfer (REST) or RESTful web services is a way to provide interoperability between computer systems on the Internet.
It is an architectural style for building distributed systems (defined by Roy Fielding in 2000), with six main constraints:

Uniform Interface - Keeping Things Consistent
- Resource identification through URIs (e.g.,/users/123, /orders)
- Manipulation of resources through representations (usually JSON today)
- Self-descriptive messages (HTTP headers tell you content-type, status, caching rules…)
- HATEOAS (Hypermedia as the Engine of Application State — optional, rarely used in practice)
Client–Server - Separation of Responsibilities
Stateless communication - Every Request Stands Alone
Cacheable - Speeding Things Up
Layered system - Scalability & Security
Code on demand - allows the server to send executable code(I have never used)

Here is a sample retail pet store project in SpringBoot, an imaginary pet store that currently sells pet fish, Aqua World.

Core REST Concepts

1. Resources and URIs (Uniform Resource Identifier)

In REST, everything is a resource — think of it as a noun (something that can be created, read, updated, deleted).
Example URI in AquaWorld App:

2. HTTP Methods & Status Codes

REST uses standard HTTP methods to express what we want to do with a resource.

Method	Meaning	Idempotent?	Common Status Codes	Typical Use Case
GET	Retrieve resource(s)	Yes	200 OK	Read data
HEAD	Same as GET but no body	Yes	200 OK	Check existence/metadata
POST	Create new resource	No	201 Created	Create user, submit form, place order
PUT	Replace entire resource	Yes	200 OK	Update/replace whole user profile
PATCH	Partially update resource	Usually	200 OK	Change only email or status
DELETE	Remove resource	Yes	204 No Content	Delete user or order

Note:

Safe methods: GET, HEAD — can be called any number of times without changing server state
Idempotent methods: GET, HEAD, PUT, DELETE — repeating the same request multiple times has the same effect as doing it once
POST is neither safe nor (strictly) idempotent — that's why it's used for creation

Common status codes everyone should know:

200 OK → success (with body)
201 Created → resource created successfully
204 No Content → success, but no response body (common for DELETE/PUT)
400 Bad Request → client sent invalid data
401 Unauthorized → authentication required
403 Forbidden → authenticated but not allowed
404 Not Found → resource doesn't exist
409 Conflict → resource conflict
500 Internal Server Error → something broke on the server side
503 Service Unavailable → service temporarily down

3. Representations & Content Negotiation

A resource can be represented in different formats.
Most common today:

JSON → application/json (the default in 2025–2026)
XML  → application/xml (still used in enterprise, SOAP legacy)

Content Negotiation — how client and server agree on format:
Client tells server what it accepts via Accept header:

Accept: application/json, application/xml;q=0.9, */*;q=0.1

Server responds with Content-Type:

Content-Type: application/json

Java Example

Steps to create a sample project:

1. Create a Spring Boot project
Use Spring initializer to create a sample project.

https://start.spring.io/

Project: Maven
Language: Java
Spring Boot: 3.3.x (Latest)
Java: 21
Dependencies:
  - Spring Web (spring-boot-starter-web)
  - Lombok (optional, for reducing boilerplate)

2. Maven Dependencies (pom.xml)

<dependencies>
    <!-- Spring Web for REST APIs -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Lombok for @Data annotation (optional) -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

3. Application Properties

pring.application.name=book-api
server.port=8080
server.servlet.context-path=/api
# Logging
logging.level.root=INFO
logging.level.com.example=DEBUG

4. Building controller
The Controller handles HTTP requests and returns responses.
In Spring Boot, we use annotations to build REST APIs. Some commonly needed Annotations:

Annotation	Purpose
@RestController	Marks the class as a REST API controller and returns JSON responses
@RequestMapping("/books")	Base path for all endpoints in this controller
@GetMapping	Maps HTTP GET requests
@PostMapping	Maps HTTP POST requests
@PutMapping	Maps HTTP PUT requests
@DeleteMapping	Maps HTTP DELETE requests
@PathVariable	Extracts values from the URL path (e.g., {id})
@RequestBody	Binds JSON request body to a Java object

Project Aquaworld

You can clone the Aqua World project and follow the steps to run the application.
Use IntelliJ IDEA or your favourite IDE to run the application.
Or run these commands in the terminal
mvn clean install
mvn start
Check out Swagger UI to run all the endpoints.

REST Design Tips

Noun-based URIs, plural collections, predictable patterns

Always use nouns for resources (not verbs):

Good: /users, /orders/123
Bad: /getUser, /createOrder

Use plural for collections: /users, /products (not /user or /usersList)
Keep patterns predictable & consistent:
/resource → collection
/resource/{id} → single item
/resource/{id}/sub-resource → nested (e.g. /users/123/orders)
Avoid deep nesting (>2–3 levels)
Use query params or references instead

Use proper status codes & error payloads

Never return a generic 200 OK with an error message in the body — it's misleading Refer codes above.
Prefer RFC 9457application/problem+json for errors (modern standard):

 JSON{
  "type": "https://example.com/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Email is already in use",
  "instance": "/users",
  "invalidParams": [ ... ]
}

Much better than plain { "error": "something went wrong" }

Basic versioning strategies

Two main approaches:
- URL versioning (most common & beginner-friendly) /v1/users, /v2/users Easy to read, cache, and route in the gateway.
- Header versioning (more RESTful) Accept: application/vnd.myapi.v2+json Cleaner URLs, but harder for humans & some clients
Avoid versioning every minor change
- Only version when you break backward compatibility (breaking changes, removing fields, changing semantics)
- Minor additions (new optional fields) → no new version needed
- Semantic Versioning rule: major version bump only for breaking changes

Testing and Tooling for REST APIs

Unit/Integration tests (Spring ecosystem)

@WebMvcTest — lightweight, fast unit test for controllers only Mocks the service layer Example

@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired MockMvc mockMvc;

    @Test
    void shouldReturnUser() throws Exception {
        mockMvc.perform(get("/users/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.name").value("John"));
    }
}

MockMvc → simulate HTTP requests without starting a full server
Use TestRestTemplate or WebTestClient for full integration tests

Contract tests
Goal: Ensure provider (API) & consumer (client) agree on contract
Popular tools:

Spring Cloud Contract
- Producer generates stubs + contract tests
- Consumer uses stubs for testing
OpenAPI/Swagger driven (most common in 2025–2026)
- Generate OpenAPI spec → use it for:
- Validation (springdoc + openapi-validator)
- Client codegen (openapi-generator)
- Contract testing (e.g. Dredd, Schemathesis, REST assured + OpenAPI)

SOLID Design Principle

Gokul G.K. — Tue, 13 Jan 2026 07:59:52 +0000

What is SOLID?

SOLID stands for: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion. Robert C. Martin popularized these principles, and they are now widely used as the foundation for maintainable object-oriented design.

SOLID is a way to manage dependencies between classes, allowing you to add features without breaking existing Code. Empirical work shows that applying SOLID tends to improve modularity, reduce coupling, and make it easier for developers to understand and extend Code.
These are some example in Java for the SOLID principle.

Single Responsibility Principle (SRP)

A class should have one, and only one, reason to change.

The chef's knife is a good example of SRP, as a tool with a single, focused responsibility: cutting. It doesn't try to be a spoon or a whisk.

package SOLID;
//A class should have only one reason to change, meaning it should have only one responsibility.
public class SingleResponsibilityPrinciple {
    //Example violating SRP
    class Employee {
        public void calculatePay() {
            //Code to calculate pay
        }
        public void saveEmployeeData() {
            //Code to save employee data to the database
        }
    }
    // Refactored classes adhering to SRP
    class PayCalculator {
        public void calculatePay() {
            //Code to calculate pay
        }
    }
    class EmployeeDataSaver {
        public void saveEmployeeData() {
            //Code to save employee data to the database
        }
    }
}

In the above code, the first version (Employee class) violates SRP because it has multiple responsibilities as it both calculates an employee's pay and saves employee data to the database.
After refactoring, these responsibilities are split into two separate classes (PayCalculator and EmployeeDataSaver), so each class has only one reason to change and follows the Single Responsibility Principle.

Open/Closed Principle (OCP)

Classes should be open for extension, but closed for modification.

A Lego brick is another good example; it's closed for modification, but can be modified by adding other bricks.

package SOLID;
/**
 * Software entities (classes, modules, functions) should be open for extension but closed for modification.
 * */
public class OpenClosePrinciple {
    //Example violating OCP
    abstract class Rectangle {
        public double area(double length, double width) {
            return length * width;
        }
    }
    // Extending Rectangle  and  modifying are
    class Square extends Rectangle {
        public double area(double side) {
            return side * side;
        }
    }
    // OCP Strategy  Use proper abstraction (most common & clean)
    interface Shape {
        double area();           // closed for modification
    }
    // Now we can add any new shape without touching the existing Code
    class Rectangleocp implements Shape {
        private double length;
        private double width;

        public Rectangleocp(double length, double width) {
            this.length = length;
            this.width = width;
        }
        @Override
        public double area() {
            return length * width;
        }
    }
    class Squareocp implements Shape {
        private double side;

        public Squareocp(double side) {
            this.side = side;
        }
        @Override
        public double area() {
            return side * side;
        }
    }
}

In the code above, the bad Example (inheritance from concrete Rectangle) forces the modification of existing Code or awkward design when adding new shapes.
The reasonable approach is to use a stable Shape interface that allows you to add any new shape by writing new classes without ever touching existing ones.

Liskov Substitution Principle (LSP)

Subtypes must be substitutable for their base types without breaking the program's expectations

Another real-life example is a universal power strip acts as a "superclass," and any plug type (US, UK, EU) is a "subclass" that can be used with it without any issues, as they all fulfill the contract of providing a power connection.

package SOLID;

/**
 * Subtypes must be substitutable for their base types without affecting the correctness of the program.
 * **/
public class LiskovSubstitutionPrinciple {
    // Example violating LSP (classic Rectangle-Square problem)
    static class Rectangle {
        protected int width;
        protected int height;
        public void setWidth(int width) {
            this.width = width;
        }
        public void setHeight(int height) {
            this.height = height;
        }
        public int area() {
            return width * height;
        }
    }
    static class Square extends Rectangle {
        @Override
        public void setWidth(int width) {
            this.width = width;
            this.height = width;   // Forces height = width
        }
        @Override
        public void setHeight(int height) {
            this.height = height;
            this.width = height;   // Forces width = height
        }
    }
    // Fixed version - separate classes implementing a common interface (recommended)
    interface Shape {
        int area();
    }
    static class RectangleFixed implements Shape {
        private int width;
        private int height;

        public RectangleFixed(int width, int height) {
            this.width = width;
            this.height = height;
        }
        public void setWidth(int width)   { this.width = width; }
        public void setHeight(int height) { this.height = height; }

        @Override
        public int area() {
            return width * height;
        }
    }
    static class SquareFixed implements Shape {
        private int side;

        public SquareFixed(int side) {
            this.side = side;
        }
        public void setSide(int side) {
            this.side = side;
        }
        @Override
        public int area() {
            return side * side;
        }
    }
    // One-liner usage example showing the violation vs fixed behavior
    public static void main(String[] args) {
        // Violating version - unexpected result when treating Square as Rectangle
        Rectangle r = new Square();
        r.setWidth(5); r.setHeight(10);                // Area should be 50, but becomes 100!
        // Fixed version - safe and predictable
        Shape rect = new RectangleFixed(5, 10);        // Area = 50
        Shape sq   = new SquareFixed(5);               // Area = 25
    }
}

The first part shows the classic LSP violation where Square extends Rectangle and overrides setters, breaking substitutability because a Square used as a Rectangle no longer behaves as expected (area becomes incorrect).
The fixed version removes inheritance between Rectangle and Square, instead having both implement a common Shape interface, ensuring any Shape can be substituted safely.

Interface Segregation Principle (ISP)

Clients should not be forced to depend on methods they do not use.

package SOLID;

/**
 * Clients should not be forced to depend on methods they do not use. Interfaces should be specific to the client's needs.
 * */
public class InterfaceSegregation {
    //Example violating ISP
    interface Worker {
        void work();
        void eat();
    }
    class Robot implements Worker {
        @Override
        public void work() {
            //Code for the robot to work
        }
        @Override
        public void eat() {
            // Robots don't eat, an unnecessary method for them
        }
    }
    // Refactored into segregated interfaces
    interface Workable {
        void work();
    }
    interface Feedable {
        void eat();
    }
    class RobotRefactored implements Workable {
        @Override
        public void work() {
            //Code for the robot to work
        }
    }
}

In the bad Example, Robot is polluted with an irrelevant eat() method just because it implements a fat Worker interface.
By splitting the interface into smaller, purpose-specific ones (Workable and Feedable), we eliminate unnecessary dependencies and make the design cleaner and more maintainable.

Dependency Inversion Principle (DIP)

Depend on abstractions, not on concrete implementations.

package SOLID;
/**
 * High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.
 * **/
public class DependencyInversion {
    //Example violating DIP
    class EmailService {
        public void sendEmail(String message, String recipient) {
            //Code to send email
        }
    }
    class UserManager {
        private final EmailService emailService;

        public UserManager() {
            this.emailService = new EmailService();
        }
        public void sendWelcomeEmail(String user) {
            emailService.sendEmail("Welcome!", user);
        }
    }
    // Refactored with abstraction
    interface MessageService {
        void sendMessage(String message, String recipient);

        void sendEmail(String s, String user);
    }
    class EmailServiceRefactored implements MessageService {
        @Override
        public void sendMessage(String message, String recipient) {
            //Code to send email
        }
        @Override
        public void sendEmail(String s, String user) {
        }
    }
    class UserManagerRefactored {
        private MessageService messageService;

        public void UserManager(MessageService messageService) {
            this.messageService = messageService;
        }
        UserManagerRefactored(MessageService messageService) {
            this.messageService = messageService;
        }
        public void sendWelcomeMessage(String user) {
            messageService.sendMessage("Welcome!", user);
        }
    }

}

In the bad Example, UserManager is tightly coupled to EmailService — making it hard to change or test.
In the refactored version, we invert the dependency; both high-level (UserManager) and low-level (EmailService, SmsService, etc.) depend on the MessageService abstraction, achieving loose coupling and flexibility.

How to tie SOLID into "system design."

Scaling teams: SOLID supports modular ownership, where different teams can evolve different modules with fewer cross‑impacts.
Evolving requirements: OCP and DIP support changing external systems or adding new features with localized changes.
Reliability and testing: Smaller, single‑responsibility classes are easier to test and mock, which helps build confidence when changing complex systems.

In brief: Why follow SOLID?
"It makes code easier to maintain, test, and extend as requirements change."

All images generated using nano banana.

Polyglot Microservices Communication in Kubernetes with DNS, CoreDNS, and Istio (Java & Python)

Gokul G.K. — Mon, 05 Jan 2026 05:33:49 +0000

Exploring service registry, service discovery, and service mesh in Kubernetes.

Here we have already discussed service discovery, registry, and service mesh.
We will discuss

How does Kubernetes implement service registry and discovery natively?
What does a service mesh add on top of Kubernetes networking?
How to test cross-service communication (Java ↔ Python) on Minikube? ### Codespace We can utilize Codespace for installation and application development. Codespaces Documentation

You can get the complete application code here

Why "polyglot" microservices are complex?

Polyglot microservices enable teams to use different programming languages and tech stacks for each service, allowing for the "best tool for the job." This introduces significant challenges in distributed systems:

Each language has its own libraries for HTTP communication, configuration management, retries, circuit breakers, and resilience patterns
Development setups (e.g., localhost) differ significantly from clustered production environments, making testing, debugging, and configuration (such as service URLs or credentials) error-prone and inconsistent.
Inter-service calls over networks can fail due to latency, timeouts, or partitions, requiring robust handling (e.g., fallbacks, timeouts) that must be re-implemented per language/stack.

Kubernetes provides native mechanisms for service discovery and networking, eliminating the need for external tools in many cases

MiniKube

MiniKube Documentation

Minikube is a local Kubernetes cluster designed to make it easy to learn and develop with Kubernetes.
Note: Local clusters enable developers to experience real Kubernetes networking (DNS, services) without relying on cloud infrastructure.

When developing locally with Minikube, you typically build Docker images on your host machine and then deploy pods that reference those images.
Minikube runs its own Docker engine inside the Minikube VM (or container, depending on the driver). This is often referred to as "Docker-in-Docker" in this context—though technically it's Docker running inside the Minikube environment, separate from your host Docker daemon.

Minikube Installation

Run below commands for installation and verfification

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Start and verify Minikube

#Start Minikube server
minikube start --driver=docker

#Verify installation
kubectl get nodes

Applications

I have already built the Java and Spring Boot applications, as well as the Kubernetes configuration file.
The project structure looks like this:

GitHub Codespace
 └── Minikube (Docker driver)
     ├── Kubernetes Services (DNS-based discovery)
     ├── FastAPI App (Python)
     ├── Spring Boot App (Java)
     ├── Istio (Service Mesh)
     │    ├── Envoy sidecars
     │    ├── mTLS
     │    └── Observability

Check the application exposed API's readme file, if you want to change/scale anything.

Java - Spring Boot application

Python - FastApi application

Build Docker Image of applications

Docker Documentation.
We will generate a Docker image from our Java and Python applications to run inside Minikube.

eval $(minikube docker-env)

If you skip eval $(minikube docker-env), your locally built images won't be visible to the cluster

docker build -t fastapi-app:1.0 ./fastapi-app docker build -t spring-app:1.0 ./spring-boot-app
This pulls in Minikube's Docker daemon, so images built inside Minikube don't need to be pushed to a registry.

Kubernetes Deployment, Service Discovery, and Service Registry

In Kubernetes, service objects and CoreDNS replace traditional service registries, such as Eureka/Consul. You don't register services manually — Kubernetes does it automatically via labels/selectors.

In Kubernetes, Service objects act as the service registry.
When a Service is created, it becomes a stable, discoverable entry that represents one or more running Pods. Pods that match a Service's selector are automatically registered as endpoints for the service.

Kubernetes provides built-in service discovery using DNS via CoreDNS.

Every service is automatically assigned a DNS name following this format:
<service-name>.<namespace>.svc.cluster.local
Applications can communicate using service names instead of IP addresses.

Check out here for Kubernetes configs and needed commands.

Once you check out the config, apply the manifest files.

kubectl apply -f KubernetesService/

Verify the Inbuilt service registry

kubectl get svc

Inspect label and selectors

Labels are key-value metadata attached to Kubernetes objects, while selectors define which labels a Service should match.

kubectl describe svc spring-service

kubectl label pod <spring-pod> app=wrong --overwrite
kubectl describe svc spring-service

Service Discovery (DNS, No Hardcoded IPs)

Let's navigate to the shell of the FastAPI service, retrieve the service name of the Spring Boot service, and verify the cross-service call.

#get the list of all pods running
kubectl get pods

#Go to the FastAPI service shell
kubectl exec -it <fastapi-pod> -- sh

#Get the IP address/service name of the spring service
getent hosts spring-service

#call the Spring service api from the FastAPI service shell.
curl http://spring-service:8080/hello

_Use the command below if curl is having issues.
_kubectl exec -it <fastapi-pod> -- sh -c "apt-get update && apt-get install -y curl && curl http://spring-service:8080/hello"

Why DNS-Only Is Not Enough?

Kubernetes's built-in DNS-based service discovery and load balancing are powerful—they give you reliable reachability: services can find each other via stable DNS names, and traffic is automatically distributed across healthy pods.

But it lacks

mLTS
Observability
Retires
Traffic Management etc

This is precisely where a service mesh steps in—adding a dedicated infrastructure layer that provides retries, traffic shaping, mTLS, and rich observability uniformly across all services, without requiring changes to the application code.

Istio / Service Mesh

Istio is an open-source service mesh that integrates seamlessly with existing distributed applications. Its powerful features provide a consistent and efficient way to secure, connect, and monitor services.

Istio Documentation

curl -L https://istio.io/downloadIstio | sh -
cd istio-*
sudo install bin/istioctl /usr/local/bin/istioctl

istioctl install --set profile=demo -y

Enable sidecar

A service mesh introduces a sidecar proxy alongside each application container.

With Istio, an Envoy proxy is automatically injected into every Pod.
All inbound and outbound traffic flows through this proxy, rather than directly between services.

kubectl label namespace default istio-injection=enabled

restaServiceice
kubectl rollout restart deployment fastapi spring

visualize sidecar
kubectl get pod <fastapi-pod> -o jsonpath='{.spec.containers[*].name}'

Sidecar enables advanced features such as:

Traffic control
Security
Observability

Most importantly, these features are added without modifying the application code, allowing teams to focus solely on business logic.

mTLS

Istio enables mutual TLS (mTLS) by default between services.

istioctl authn tls-check spring-service.default.svc.cluster.local
Service Mesh mTLS provides:

Encryption in transit
Service identity verification
Zero-trust networking

All of this happens transparently; applications are completely unaware that encryption is being handled in the background.

Observability

A service mesh provides deep observability out of the box.
Because all traffic flows through Envoy proxies, Istio can automatically collect:

Request rates
Latency
Error percentages
Service dependencies Tools like Kiali visualize this data as a live service graph, making it easy to understand how services interact and where problems occur.

Achieving this level of insight is extremely challenging at the application level alone.

kiali Documentation

install kiali
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.28/samples/addons/kiali.yaml

Sample Dashboard

All images generated using nano banana.
Reference added section-wise.

This is a very brief demonstration of how service discovery, service registry, and service mesh work. I will be creating a detailed version focusing on Service Mesh (Istio) and Observability tool (Kiali)

Let's talk about service discovery, service registry, and service mesh.

Gokul G.K. — Sun, 28 Dec 2025 13:11:03 +0000

How Do Our Microservices Find Each Other and Communicate With Each Other?

Imagine a system with over 50 microservices, each running on a different machine.
Instances scale up and down, IPs change, services crash and restart.

Yet somehow, everything still works.
So the natural questions arise:

How do microservices find each other?
How do they know where an upstream service is running?
How do they communicate securely and reliably at scale?

To answer these questions, we need to understand three key concepts:

Service Registry
Service Discovery
Service Mesh

The Core Problem

In a distributed microservices system:

Services don’t have fixed IP addresses
Instances are created and destroyed dynamically
Hardcoding endpoints is impossible
Manual configuration does not scale

So we need a dynamic, automated way for services to:

Know what services exist
Find where they are currently running
Communicate securely and reliably

Service registry

It's a database that will store network information for all registered instances. It's a key part of service discovery; the registry must be up-to-date and highly available.

Typical service registries (pre-Kubernetes):

Eureka
Consul
Zookeeper

Service Registration

Service instances need to be registered and deregistered with the service registry in all types of service discovery.

Self Registration

The service instance itself handles registration and deregistration with the service registry. It registers its address with the registry and immediately deregisters itself when the instance terminates.

Third-party Registration

The third-party registration pattern prevents service instances from self-registering. Instead, the registration and deregistration processes are managed by the service registrar, a component that monitors changes in the set of running instances.

Service Discovery

Service discovery is the mechanism by which a service finds the network location of another service at runtime.

The primary goal of service discovery is to simplify communication between microservices, enabling automatic connection through a dedicated system. Instead of hardcoding the network address, we tend to ask where the service is.

How does it work?

Service discovery involves three key functions: it allows an instance to register and announce, "I’m here!" It also provides a method to locate the service after registration. Finally, it updates any changes in the service's location.

In more detailed steps (a generalized version)

Service Instance Starts - A microservice instance starts on a VM. It gets an IP address dynamically (payment service)
Service Registers Itself - The service registers with a service registry. It sends: Service name, IP address, Port, Health info payment-service → 10.0.1.12:8080
Registry Stores Metadata - The registry maintains a list of healthy service instancesPeriodic heartbeats update health(orange box)
Client Requests a Service- A client service (order service) requests a call to the payment service. It queries the registry
Service Discovery Happens - Registry responds with:[10.0.1.12, 10.0.1.15, 10.0.1.18]
Load Balancing - Client picks one instance, makes the network call. This is client-side discovery
Health Updates - Failed instances are removed, Registry stays up-to-date

There are two main service discovery patterns: client-side discovery and server-side discovery.

Client-Side Discovery Pattern

In the client-side discovery pattern, the client/consumer service (in this case, the order service) is responsible for determining the network location and load-balancing the request between them.

It has an advantage because it saves an additional step that would have been needed with a dedicated load balancer. However, it also has a disadvantage as the Service Consumer must implement the load-balancing logic.

Server-side Discovery Pattern

In the server-side discovery pattern, there is an intermediary layer of router/load balancer. The client makes a discovery and communicates through this load balancer, which acts as an orchestrator.

In this approach, a dedicated component called the Load Balancer handles the task of load balancing. This is a major advantage, as it simplifies the responsibilities of the Service Consumer, which no longer has to manage the lookup process. Consequently, there's no need to implement discovery logic separately for each programming language or framework used by the Service Consumer.
It is essential to note that we must either set up and manage the Load Balancer ourselves or ensure it is already available in the deployment environment.

In Kubernetes-based systems, you usually do not need a separate service registry or discovery tool.
But Discovery Alone Is Not Enough

Even with discovery solved, new challenges appear:

How do services communicate securely?
How do we handle retries and failures?
How do we prevent cascading outages?
How do we apply consistent policies across services written in different languages?
This is where service mesh comes in.

Service mesh

A Service Mesh is a method for managing communication between individual services that comprise modern applications in a microservice-based architecture. It helps to add security, reliability, and observability.
Service Mesh enables security, observability, traffic management, and reliability.

The dedicated infrastructure layer of a service mesh complements an API gateway, serving a distinct purpose. While a service mesh manages communication between the various services within a system, an API gateway separates the internal workings of that system from the API that is presented to clients, which can include other systems within the organization or external clients.

The distinction between an API gateway and a service mesh is often described in terms of north-south (for the API gateway) versus east-west (for the service mesh) communication. However, this characterization may not fully capture the nuances of their respective functions.

How does a service mesh work?

Architecture: Data Plane vs. Control Plane
A service mesh is split into two distinct parts:

1. The Data Plane (The Muscle)
This consists of the thousands of intelligent sidecar proxies deployed throughout your cluster.

The Data Plane handles the actual data packets, performs load balancing, terminates TLS (encryption), enforces rate limits, and collects metrics (including latency and error rates). These proxies are highly optimized to add minimal latency (milliseconds).

2. The Control Plane (The Brain)
This is a centralized management server. The proxies are stateless; they require instructions on what to do.

The control plane manages and configures the proxies. The Control Plane then pushes this configuration to all the Data Plane proxies in real-time. It often acts as a Certificate Authority (CA), rotating security certificates for the proxies to use.

Step-by-Step: How a Request Works

Imagine Service A (Frontend) wants to call Service B (Inventory).

Outbound Intercept: Service A sends a request to Service B. The network rules trap this packet and redirect it to Service A's local sidecar proxy.

Discovery & Load Balancing: The sidecar asks, "Where is Service B?" It examines its configuration (from the Control Plane) and selects the best instance of Service B (e.g., the one with the lowest latency).

Encryption (mTLS): The sidecar encrypts the request using a mutual TLS certificate to ensure no one else can read it.

Transmission: The encrypted request travels over the network to the machine where Service B is running.

Inbound Intercept: The request is caught by Service B's sidecar proxy.

Decryption & Check: Service B's sidecar decrypts the packet and verifies that Service A is authorized to communicate with Service B (Access Control).

Delivery: If allowed, the sidecar forwards the clean request to the actual Service B application.

Reference

1.https://www.baeldung.com/cs/service-discovery-microservices
2.https://www.f5.com/company/blog/nginx/service-discovery-in-a-microservices-architecture
3.https://middleware.io/blog/service-discovery/
4.https://api7.ai/blog/service-discovery
5.https://microservices.io/tags/service%20discovery
7.https://konghq.com/blog/learning-center/what-is-a-service-mesh
*Images generated using nano banana

I wrote these blogs based on my understanding and research. Please comment if you find any errors or suggest improvements.

Getting Started with Prometheus and Grafana in Java

Gokul G.K. — Thu, 14 Nov 2024 00:02:29 +0000

Monitoring is a crucial aspect of application performance management. As applications scale, ensuring that they run smoothly and that system health is continually tracked becomes imperative. In microservices, distributed systems, and cloud-native applications, monitoring tools are not just an add-on but a critical part of your infrastructure.

Two of the most popular tools for monitoring modern systems are Prometheus and Grafana. These tools are often used to collect, store, and visualize metrics, helping developers and operations teams detect issues, analyze performance, and keep systems running efficiently.

Why Do We Need Monitoring?

Monitoring is essential for identifying problems before they affect users. Whether you're working with a Java-based backend, a complex microservices environment, or any other system, continuous monitoring provides insights into:

Application performance:
Track key performance metrics such as response times, requests, and error rates.
System health:
Monitor server health, CPU usage, memory usage, and disk space to ensure the infrastructure operates optimally.
Alerting:
Set up thresholds and alerts for critical metrics that notify you when something goes wrong.
Capacity planning:
Collecting and analyzing historical data can help you plan for scaling your application.

Prometheus and Grafana offer robust solutions to monitor, visualize, and analyze data from your systems and applications.

Introducing Grafana and Prometheus

Prometheus
Prometheus is an open-source monitoring and alerting toolkit designed for reliability and scalability. It focuses on gathering time-series data and supports multidimensional data collection, allowing for powerful queries and analysis. Prometheus collects metrics from targets via HTTP endpoints and stores them in a time-series database. These metrics can then be queried using Prometheus's query language, PromQL.

Grafana
Grafana is an open-source platform for monitoring and observability. It allows users to visualize time-series data from multiple sources, including Prometheus. Grafana's ability to create dashboards, set up alerts, and integrate with a wide range of data sources makes it one of the most popular tools for visualizing metrics.

Together, Prometheus collects the metrics, while Grafana displays them in an interactive and visually appealing way.

Running Prometheus in Docker

Running Prometheus and Grafana in Docker is a simple and effective way to set up a monitoring environment quickly. Let's start with running Prometheus in Docker.

Step 1: Running Prometheus in Docker
You can run Prometheus as a container using the following command:

docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus

This command will:

Start a Prometheus container.
Map the local port 9090 to the container’s port 9090.
Use the official Prometheus Docker image from Docker Hub. You can verify that Prometheus is running by opening your browser and navigating to http://localhost:9090/.

Step 2: Configuring Prometheus
You must adjust the Prometheus configuration file if you need to configure Prometheus to scrape metrics from specific endpoints (e.g., a Java application). By mounting it into the container, you can run Prometheus with a custom prometheus.yml file. Here’s an example:

docker run \
    -p 9090:9090 \
    -v /prometheus.yml:/etc/prometheus/prometheus.yml \
    prom/prometheus

This mounts your local prometheus.yml file into the container. After starting Prometheus, you can go to http://localhost:9090/ to access the Prometheus dashboard.

Running Grafana in Docker

Now that Prometheus is running adding Grafana to visualize the data is time.

Step 3: Running Grafana in Docker
Grafana is simple to deploy via Docker. Run the following command to start the Grafana container:

Running Grafana in docker

docker run -d -p 3000:3000 grafana/grafana-enterprise

Once Grafana is running, you can access the web UI at http://localhost:3000/login. The default login credentials are:

Username: admin
Password: admin

Step 4: Connecting Prometheus and Grafana
Now that both Prometheus and Grafana are running, the next step is to connect them. Grafana needs to know where to get the metrics from. Here's how you can add Prometheus as a data source in Grafana:

Log in to Grafana.
click the gear icon on the left sidebar to open the Configuration menu.
Select Data Sources.
Click Add data source.
Choose Prometheus as the data source type.
In the HTTP section, set the URL to your Prometheus instance (e.g., http://172.0.0.1:9090).
Click Save & Test to ensure Grafana can successfully connect to Prometheus.

Creating a Sample Java Project

Let's create a simple Java-based project that exposes metrics to Prometheus. We will use Micrometer, a metrics collection facade for JVM-based applications, which integrates easily with Prometheus.

Step 5: Create a Java Application

Add the necessary dependencies to your pom.xml file:
Connecting everything.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Then, in your Java application, expose an endpoint that Prometheus can scrape. For example:

import io.micrometer.core.instrument.Metrics;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.micrometer.prometheus.PrometheusMeterRegistry;

@SpringBootApplication
public class MonitoringApp {

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

@RestController
class MetricsController {

    private final PrometheusMeterRegistry registry;

    public MetricsController(PrometheusMeterRegistry registry) {
        this.registry = registry;
    }

    @GetMapping("/metrics")
    public String getMetrics() {
        return registry.scrape();
    }
}

This setup creates an endpoint /metrics that Prometheus can scrape. It exposes metrics collected by Micrometer and is available in the Prometheus format.

Step 6: Expose Metrics to Prometheus
Now that the Java application is collecting metrics, we need to tell Prometheus to scrape the /metrics endpoint from your application. Update your prometheus.yml configuration file to include the target:

scrape_configs:
  - job_name: 'java_application'
    static_configs:
      - targets: ['<your-app-ip>:8080']

Replace with the IP address or localhost if running on the same machine. Prometheus will now collect metrics from your Java application.

Connecting Everything

At this point, you have:

Prometheus scraping metrics from your Java application.
Grafana is set up as the visualization tool.

Step 7: Creating Dashboards in Grafana
To visualize the data in Grafana:

Go to the Dashboard tab in Grafana.
Click + New Dashboard.
Add a Panel and select Prometheus as the data source.
Write a PromQL query to retrieve the metrics, for example, http_requests_total.

You can now build a dashboard with various panels that show metrics like request counts, response times, and error rates.

Monitoring is crucial for maintaining high availability and performance. With tools like Prometheus and Grafana, you can easily set up an efficient monitoring solution for your Java applications.

Let's create a website with NextJS and deploy it with Vercel.

Gokul G.K. — Tue, 12 Nov 2024 17:21:04 +0000

Building and deploying a website with Next.js is easier than you might think, and the best part? It's platform-agnostic, so the steps remain the same whether using macOS, Windows, or Linux. In this guide, I'll walk you through creating a Next.js app, setting it up locally, and deploying it to Vercel with just a few simple commands.

1. Set Up Your Next.js Project Start by creating a new Next.js app. Open your terminal, and run the following command:

npx create-next-app@latest my-website
-- Click yes for all dependencies

This will create a new Next.js project in a folder called my-website. When prompted, click "Yes" to install all necessary dependencies.

Next, navigate to your project folder:

 cd my-website

2. Ensure Node is Installed If you encounter any issues while setting up your project, it's likely due to an outdated version of Node.js. To fix this, you can install the latest version of Node:

nvm install node --latest-npm

Ensure you have the correct Node.js version installed by checking the Next.js installation guide for the latest version requirements.

3. Open the Project Files Once the project is set up, open your project folder in your preferred code editor. You should see a file structure similar to the one below:

Note that the app name I've used here is portfolio2.0, but feel free to name your project whatever you like. If you want more details on these files, check out the Next.js Project Structure documentation.

4. Install Dependencies Next, install the necessary dependencies:

npm install

After installation, you can run your app locally to see it in action. Head to http://localhost:3000 in your browser, and you should see the Next.js default page!
.

5.Push Code to GitHub

Now that your app is set up locally push the code to your GitHub repository. You'll need this to deploy it to Vercel.

6.Deploy to Vercel
Sign up for Vercel:
If you don't have a Vercel account, sign up at vercel.com. You can use your GitHub account for easy integration.
Connect Vercel to GitHub:
Once signed in to Vercel, link your GitHub account to your Vercel dashboard.
Import Your GitHub Repository:
Click "New Project" in your Vercel dashboard.
Select "Import Git Repository" and choose the repository containing your Next.js project.
Configure the Project:
Vercel will automatically detect that your project is built with Next.js.
Set the build command to the next build.
Set the output directory to .next (this is usually auto-configured).
Add any environment variables you might need (optional).
Deploy Your Project:
Click "Deploy," and Vercel will start the deployment process.
Vercel will clone your repository, install the dependencies, build your app, and deploy it.
Wait for the Deployment to Complete:
Vercel will provide real-time deployment logs so you can follow along with the process.
Access Your Live Site:
Once deployment is finished, you'll receive a link to your site, which will look like your-project-name.vercel.app. That's it! Your Next.js app is now live.

Quick Recap: Steps for Any Next.js Project

Prepare Your Next.js Project:
Ensure your project is in a GitHub repository with a package.json file containing the necessary scripts (next dev, next build, next start).

Sign Up for Vercel:
Head to Vercel's website and sign up using your GitHub account.

Connect Vercel to GitHub:
Link your GitHub account in the Vercel dashboard.

Import Your GitHub Repository:
In the Vercel dashboard, click "New Project" and choose your GitHub repository.

Configure Your Project:
Vercel automatically detects Next.js projects and configures most settings. You can fine-tune settings if needed.

Deploy:
Click "Deploy" and let Vercel handle the rest. It will build and deploy your app automatically.

Wait for the Deployment:
You can monitor the deployment logs in real-time.

Check Your Live Site:
Once deployment is complete, Vercel will give you a URL to access your site.

What would you do if your encrypted credentials and the key got compromised?

Gokul G.K. — Mon, 11 Jul 2022 16:50:09 +0000

What will you do if your encrypted credentials and key got compromised?

This is a rhetorical question.

Securing API using API keys, tokens or password is common in any application. In the case of basic authentication generally, we try to store the credentials after encrypting them. Here let's see how we can use one-way hash functions like md5 or SHA-256 to achieve basic authentication.

The Idea

The idea is to have the credentials converted to hash strings using hash functions for the first time or during sign-up. During login, convert the user entered credentials to hash string and check for equality. Simple as that :D.

Here we aren't storing any encrypted passwords, so even if there is an attack on your application and data is compromised, your credentials are safe.

The Implementation

For a complete implementation of the same using java and spring boot (click here)

let me do a walkthrough :

so we have a minimal controller interface and implementation

@RestController
public interface LoginApi {

    @GetMapping("/user/login")
    @ResponseBody
    String userLogin();
}

@Component
public class LoginApiImpl implements LoginApi{

    /**
     * User login string.
     *
     * @return the string
     */
    @Override
    public String userLogin() {
        return "Login Successful";
    }
}

Then we have the filter implementation to verify authentication
Basic Authentication Filter Implementation

The service implementation is where we check the hashed string and given credential, for simplicity let's focus on password.

/**
 * The type Login service.
 */
@Service
public class LoginService {

    /**
     * The constant USER.
     */
    private static final String USER = "ADMIN";

    /**
     * The constant PASSWORD.
     * Actual value is : password
     */
    private static final String PASSWORD = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8";

    /**
     * Check authentication boolean.
     *
     * @param user     the user
     * @param password the password
     * @return the boolean
     * @throws NoSuchAlgorithmException the no such algorithm exception
     */
    public boolean checkAuthentication(String user,String password) throws NoSuchAlgorithmException {
        String generatedHash = generateHash(password);
        if(PASSWORD.equals(generatedHash) && USER.equals(user))
            return true;
        return false;
    }

    /**
     * Generate hash string.
     *
     * @param password the password
     * @return the string
     * @throws NoSuchAlgorithmException the no such algorithm exception
     */
    public  String generateHash(String password) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] hash =  md.digest(password.getBytes(StandardCharsets.UTF_8));
        BigInteger number = new BigInteger(1, hash);
        StringBuilder hexString = new StringBuilder(number.toString(16));
        while (hexString.length() < 64)
        {
            hexString.insert(0, '0');
        }
        return hexString.toString();
    }
}

finally, let's run the code and hit the API {in this example username is: ADMIN and password is: password}

Here is the curl for the above API: curl --location --request GET 'http://localhost:8443/service/api/v1/user/login' \
--header 'Authorization: Basic QURNSU46cGFzc3dvcmQ='

That's all for now, Hope this is useful.
Share your thoughts in the comment section.

DEV Community: Gokul G.K.

Design pattern visualization: Structural Design Patterns

Adapter

Class Diagram

Bridge

Class Diagram

Composite

Class Diagram

Decorator

Class Diagram

Facade

Class Diagram

Flyweight

Class Diagram

Proxy

Class Diagram

Structural Design Patterns: Real-World & Technical Examples

Design pattern visualization: Creational Design Patterns

Factory Method

Quick Explanation of the Diagram

Abstract Factory Method

Quick Explanation of the Diagram

Singleton

Quick Explanation of the Diagram

Prototype

Quick Explanation of the Diagram

Builder

Quick Explanation of the Diagram

Creational Design Patterns Overview

API designs for microservice comparison.

1. High-Level Architectural Comparison

2. Performance & Efficiency

3. Developer Experience & Tooling

4. Security & Caching

5. Versioning & Evolution

Implementing gRPC.

Core Principle

gRPC vs REST API: Comparison Table

Java Implementation

gRPC Design and Best Practices

API Versioning in gRPC

Error Handling in gRPC

Deadlines, Timeouts, Retries, and Load Balancing

Choose gRPC if you need:

GraphQL for Beginners

Why GraphQL Emerged: Solving the Pain Points of REST APIs

The Over-Fetching and Under-Fetching Problems in REST

GraphQL as a Query Language and Schema-Based Runtime

Core GraphQL Concepts: Building Blocks for Powerful APIs

The Schema: Types, Queries, Mutations, and Strong Typing.

Operations: Queries, Mutations, and Subscriptions

Resolvers: The Data-Fetching Glue

Java Code Example.

REST vs GraphQL

AquaWorld Endpoint Comparison

Data Fetching Comparison

Quick Start Guide

GraphQL Endpoint

GraphQL Annotations in Spring Boot (spring-graphql)

GraphQL Design and Best Practices: Building APIs That Age Gracefully

Getting started with the REST API in Spring Boot.

What is REST?

Core REST Concepts

1. Resources and URIs (Uniform Resource Identifier)

2. HTTP Methods & Status Codes

Note:

Common status codes everyone should know:

3. Representations & Content Negotiation

Java Example

Steps to create a sample project:

REST Design Tips

Testing and Tooling for REST APIs

SOLID Design Principle

What is SOLID?

Single Responsibility Principle (SRP)

Open/Closed Principle (OCP)

Liskov Substitution Principle (LSP)

Interface Segregation Principle (ISP)

Dependency Inversion Principle (DIP)

How to tie SOLID into "system design."

GraphQL Annotations in Spring Boot (`spring-graphql`)