DEV Community: Jane

Mastering Custom API Response in Java Spring Boot

Jane — Fri, 08 May 2026 10:00:30 +0000

When you start building APIs in Spring Boot, things feel simple at first. You return objects, and Spring automatically converts them into JSON. But as your application grows, problems begin to appear:

Different APIs return different response formats
Error handling becomes messy
Frontend developers struggle to handle multiple structures
Debugging becomes time-consuming

This is where a Custom API Response structure becomes extremely important.

In this blog, we will deeply understand not just how to implement it, but also why each part exists and how it helps in real-world projects.

Problem with Default API Design

Let’s take a real scenario.

Case 1: Success API

{
  "id": 1,
  "name": "Ayush"
}

Use our Online Code Editor

Case 2: Error API

{
  "message": "User not found"
}

Use our Online Code Editor

Case 3: Validation Error

{
  "errors": [
    "Name is required",
    "Email is invalid"
  ]
}

Use our Online Code Editor

What Breaks Here

Now the frontend must write logic like:

Check if id exists → success
Check if message exists → error
Check if errors exists → validation

This creates unnecessary conditional handling across web, mobile, and third-party clients.

As APIs scale, inconsistent contracts increase maintenance costs.

Solution: Standard API Response

We fix this by defining a fixed structure:

{
  "data": {},
  "success": true,
  "message": "Request successful",
  "errors": null,
  "status": "OK",
  "timestamp": "2026-04-28T10:00:00"
}

Use our Online Code Editor

Why Each Field Exists

data → Holds actual response (can be object, list, or null)
success → Quick boolean check (frontend friendly)
message → Human-readable message
errors → Detailed error info (useful for debugging)
status → HTTP status for clarity
timestamp → Helps in tracking and debugging issues

This makes your API predictable and easy to consume.

Step 1: StandardResponse Class

public class StandardResponse<T> {

    private T data;
    private boolean success;
    private String message;
    private Object errors;
    private HttpStatus status;
    private LocalDateTime timestamp;

    public StandardResponse(T data, boolean success, String message,
                            Object errors, HttpStatus status) {
        this.data = data;
        this.success = success;
        this.message = message;
        this.errors = errors;
        this.status = status;
        this.timestamp = LocalDateTime.now();
    }
}

Use our Online Code Editor

Deep Explanation

Generic <T>
- Makes the class reusable for any data type
- Example: String, User, List<User>
Object errors
- Flexible → can store string, list, or map
- Useful for validation errors
timestamp
- Helps track when API was called
- Useful in logs and debugging production issues

This class becomes the backbone of your API.

Step 2: ResponseBuilder (Why It Matters)

Without a builder, you would write this everywhere:

new StandardResponse<>(data, true, "Success", null, HttpStatus.OK);

Use our Online Code Editor

This is repetitive and error-prone.

Solution:

public class ResponseBuilder {

    public static <T> StandardResponse<T> success(T data, String message) {
        return new StandardResponse<>(data, true, message, null, HttpStatus.OK);
    }

    public static <T> StandardResponse<T> error(String message, Object errors, HttpStatus status) {
        return new StandardResponse<>(null, false, message, errors, status);
    }
}

Use our Online Code Editor

Why This Matters

Reduces code duplication
Improves readability
Central place to modify response logic
Makes your code cleaner
Supports cleaner architecture

Step 3: Service Layer

public StandardResponse<String> getUser() {
    String user = "Ayush";
    return ResponseBuilder.success(user, "User fetched successfully");
}

Use our Online Code Editor

Why This Is Good Design

Business logic stays clean
No HTTP logic here
Only returns a structured response

This follows Separation of Concerns

Step 4: Controller Layer

@GetMapping("/user")
public ResponseEntity<StandardResponse<String>> getUser() {
    return ResponseEntity.ok(userService.getUser());
}

Use our Online Code Editor

Why Use ResponseEntity?

Allows control over HTTP status
Can add headers if needed
Makes API more flexible

Even though the response has a status inside, the HTTP status is still important.

Global Exception Handling (Very Important)

Instead of:

try {
   // logic
} catch(Exception e) {
   // handle
}

Use our Online Code Editor

Use centralized handling:

@RestControllerAdvice
public class GlobalExceptionHandler {

Use our Online Code Editor

Why?

Centralized error handling
No repeated try-catch
Cleaner code
Consistent error response

Step 6: Validation Handling (Advanced Understanding)

When using @Valid, Spring throws:

MethodArgumentNotValidException

Use our Online Code Editor

We handle it like this:

List<String> errors = ex.getBindingResult()
    .getFieldErrors()
    .stream()
    .map(err -> err.getField() + ": " + err.getDefaultMessage())
    .toList();

Use our Online Code Editor

What This Does

Extracts all validation errors
Converts them into readable messages
Sends them in response

Example Output:

"errors": [
  "email: must be valid",
  "name: must not be blank"
]

Use our Online Code Editor

Step 7: Real-World Enhancements

1. Error Codes

Instead of just a message:

"errorCode": "USER_NOT_FOUND"

Use our Online Code Editor

Helps frontend and logging systems.

2. Request ID (Tracing)

In microservices:

"requestId": "abc-123-xyz"

Use our Online Code Editor

Helps track requests across services.

3. Pagination Support

{
  "data": {
    "content": [],
    "page": 1,
    "size": 10,
    "totalElements": 100
  }
}

Use our Online Code Editor

Important for large datasets.

4. Execution Time

Track performance:

long start = System.currentTimeMillis();

Use our Online Code Editor

Helps optimize slow APIs.

Common Mistakes to Avoid

Returning raw entities directly
Mixing multiple response formats
Not handling exceptions globally
Ignoring validation errors
Hardcoding messages everywhere

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Why Backend Teams Use Standard API Responses in Spring Boot

Jane — Thu, 07 May 2026 10:00:30 +0000

Building APIs is not just about returning data. It’s about returning the data in a way that stays clear, predictable, and easy to work with as your system grows.

Which is why backend teams tend to use standard API responses in Spring Boot. Whenever an endpoint follows a consistent structure, frontend integration becomes smoother, debugging gets faster, and maintenance becomes far less painful.

This guide breaks down how standard API responses work in Spring Boot and why they matter in real projects.

Understanding Standard API Responses in Spring Boot

Standard API responses in Spring Boot mean returning data in a consistent way across all endpoints. Instead of sending different JSON shapes, the application follows one predictable response structure.

This is important because APIs are more like contracts, and whenever a response changes randomly between endpoints, frontend apps, mobile clients, and third-party integrations become harder to maintain.

A standard response includes fields like:

success – if a request was completed successfully
message – human-readable summary
data – actual payload returned by the API
errors – validation or business errors
timestamp – when a response was generated

Example:

{
  "success": true,
  "message": "User fetched successfully",
  "data": {
    "id": 101,
    "name": "Ada"
  },
  "timestamp": "2026-04-29T10:00:00Z"
}

Use our Online Code Editor

Example error response:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": "Email is required"
  },
  "timestamp": "2026-04-29T10:01:00Z"
}

Use our Online Code Editor

This helps to know where to find values without checking every endpoint separately.

In Spring Boot, standard responses are mostly implemented using DTOs or wrapper classes. Instead of returning raw entities directly from controllers, responses are wrapped in a shared model.

Example:

public class ApiResponse<T> {
    private boolean success;
    private String message;
    private T data;
}

Use our Online Code Editor

Then a controller can return:

return ResponseEntity.ok(
    new ApiResponse<>(true, "User loaded", userDto)
);

Use our Online Code Editor

Standard responses do not mean every endpoint must return identical payload sizes or force unnecessary wrappers. Lightweight endpoints can stay simple while still following the same contract. The most important thing is structural consistency.

Spring Boot teams often combine standard responses with:

ResponseEntity for status codes
@ControllerAdvice for global error handling
DTOs for clean payloads
validation annotations for input errors

Try as much as possible to avoid exposing raw database entities, as they often contain internal fields, lazy-loaded relationships, or unstable shapes. DTO-based responses are somewhat safer and clearer.

When backend teams standardize responses early, APIs become easier to scale, test, document, and consume. That is why consistent API response design is considered a smart long-term practice in Spring Boot applications.

What Standard API Responses Mean in Backend Development

Standard API responses mean your backend returns data using a consistent structure across endpoints. Instead of one route returning raw objects, another returning nested arrays, and another returning plain text, the API follows a predictable format.

Doesn't matter if the client is a web app, mobile app, internal dashboard, or third-party integration. Predictable responses reduce confusion and speed up development. Consumers know where to find the message, payload, errors, and metadata without reading custom logic for each endpoint.

A common standard response format includes:

success – indicates request outcome
message – short explanation of the result
data – requested resource or payload
errors – validation or processing issues
timestamp – response time marker

Example:

{
  "success": true,
  "message": "Products retrieved successfully",
  "data": [
    { "id": 1, "name": "Keyboard" },
    { "id": 2, "name": "Mouse" }
  ]
}

Use our Online Code Editor

Example error response:

{
  "success": false,
  "message": "Invalid request",
  "errors": {
    "email": "Email format is invalid"
  }
}

Use our Online Code Editor

This does not mean every response should be identical. It means every response should be understandable in the same way.

In backend development, standard responses solve common problems like:

Frontend integration becomes easier*:* UI teams can build reusable handlers for loading states, success notifications, and error messages.
Testing becomes faster*:* Automated tests can validate common fields across endpoints.
Documentation becomes clearer: API consumers see repeatable patterns instead of dozens of unrelated response shapes.
Debugging improves: Logs and monitoring tools can parse errors consistently.

Standard API responses also work closely with proper HTTP status codes.

By using:

200 OK for successful reads
201 Created for new resources
400 Bad Request for validation failures
401 Unauthorized for auth issues
404 Not Found for missing resources
500 Internal Server Error for unexpected failures

The JSON body gives details while the status code gives protocol meaning.

Avoid common mistakes like:

Returning raw database entities directly
Using different field names for the same concept (msg, message, detail)
Returning 200 OK for failed operations
Sending inconsistent error formats

A strong backend treats response design as part of architecture, not an afterthought. Standard API responses help systems to stay maintainable as teams, features, and integrations grow.

Why Consistent API Response Structure Matters

A consistent API response structure matters a lot because APIs are used repeatedly by humans, applications, and automated systems. If every endpoint responds differently, complexity tends to grow faster.

When each response follows the same pattern, developers know exactly where to look for data, status messages, errors, and metadata. This saves time during integration and lowers the chance of bugs.

Example:

{
  "success": true,
  "message": "Order retrieved",
  "data": {
    "id": 45
  }
}

Use our Online Code Editor

Than a system where one endpoint returns:

{ "result": {...} }

Use our Online Code Editor

Another returns:

{ "payload": {...} }

Use our Online Code Editor

And another returns:

{ "responseData": {...} }

Use our Online Code Editor

Frontend development becomes faster when responses are standardized, UI teams can build reusable components for:

success notifications
form validation errors
loading states
pagination handlers
empty state messages

Instead of rewriting logic for every API route, one pattern can serve many endpoints, and testing becomes simpler.

Automated tests can verify common fields like:

success
message
data
error structure

This speeds up regression testing and improves confidence during releases.

If production issues occur, consistent error payloads help logs, dashboards, and monitoring tools identify problems quickly.

API docs become easier to read when consumers recognize a repeatable contract. New team members onboard faster because they learn one pattern instead of many.

Example:

{
  "success": true,
  "message": "Users fetched",
  "data": [...]
}

Use our Online Code Editor

The data Content may expand over time, but the outer structure remains familiar.

Avoid common mistakes like:

Mixing naming styles (snake_case, camelCase) randomly
Returning strings for some errors and objects for others
Using success responses with failure messages
Returning different pagination formats across list endpoints

A file download endpoint, streaming endpoint, or webhook callback may need different behavior. But for normal JSON APIs, a shared structure creates long-term stability.

Common Problems Caused by Inconsistent Responses

Inconsistent API responses create confusion fast. The same concept appears under different names, and clients are forced to guess how each endpoint behaves.

One endpoint returns:

{ "data": {...} }

Use our Online Code Editor

Another returns:

{ "result": {...} }

Use our Online Code Editor

Another returns:

{ "payload": {...} }

Use our Online Code Editor

This breaks predictability, and every new endpoint requires fresh parsing logic.

UI code becomes harder to maintain. Instead of one reusable handler, multiple condition checks are needed for different response shapes.

Example:

checking data in one endpoint
checking response in another
checking nested structures somewhere else

This leads to duplicated logic and more bugs, and having inconsistent error formats can be a major issue.

One endpoint returns:

{ "error": "Invalid input" }

Use our Online Code Editor

Another returns:

{ "errors": { "email": "Required" } }

Use our Online Code Editor

This makes it difficult to build a unified error handling system. Validation messages may not display correctly, and some errors may go unnoticed.

When something breaks in production, inconsistent responses slow down investigation, and logs become harder to read.

APIs are expected to behave consistently when responses change unpredictably, and integrations become fragile.

A small backend change can silently break:

mobile apps
frontend dashboards
third-party integrations

This leads to unexpected failures and harder rollouts.

API documentation should serve as a guide to users. Inconsistent responses force documentation to include exceptions and special cases for every endpoint.

Inconsistent API responses do not just affect code readability. They impact performance, reliability, and team productivity. Consistency removes friction and keeps systems manageable as they grow.

How Smart Backend Teams Benefit from Standardization

Standardizing API responses gives backend teams a shared contract. Everyone builds against the same structure, which removes ambiguity and speeds up development.

You spend less time deciding how to return data and more time focusing on business logic. When a standard response format exists, new endpoints follow a known pattern. Instead of designing response structures repeatedly, teams reuse:

a common response wrapper
consistent error formats
shared status handling

This reduces decision fatigue and speeds up delivery.

APIs change over time. Standard responses make these changes easier to manage.

You can:

keep the outer response structure stable
evolve the inner data payload
avoid breaking existing clients

This leads to smoother upgrades and fewer disruptions.

Smart backend teams treat API response design as part of system architecture. Standardization is not just about consistency it directly impacts speed, reliability, and long-term maintainability.

Have a great one!!!

Author: Toluwanimi Fawole

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

How to Become an AI Engineer from a Java Developer Using Spring AI

Jane — Wed, 06 May 2026 10:00:30 +0000

The world is quickly moving towards Artificial Intelligence, and many Java developers are now thinking about how they can transition into AI engineering. The good news is you don’t need to start from scratch. If you already know Java and Spring Boot, you already have a strong foundation. With tools like Spring AI, the journey becomes much easier and practical.

Let’s understand this step by step in a simple and realistic way.

Start with the Right Mindset

Before jumping into tools and code, you need to understand one thing: AI engineering is not only about machine learning models. It is also about building real-world applications that use AI.

As a Java developer, you already know how to build scalable systems, APIs, and backend logic. Now you just need to learn how to integrate AI into those systems.

Think like this:

Earlier → You were building APIs

Now → You will build intelligent APIs

Learn Basic AI Concepts (No Deep Math Required)

You don’t need to become a data scientist. Just focus on understanding:

What is AI and Machine Learning
What is a Large Language Model (LLM)
What is Prompt Engineering
Basics of embeddings and vector databases

Example:

If a user asks, “Suggest me a good laptop under 50k,” an AI system can understand the intent and generate a helpful answer. You don’t need to train the model; you just need to use it correctly.

Understand How APIs Work with AI

Most modern AI systems, like GPT models, are accessed using APIs. This is where your Java experience helps a lot.

You already know:

REST APIs
JSON handling
HTTP calls

Now you just need to call AI APIs and process responses.

Example:

Imagine you are building a customer support system. Instead of writing static responses, you can call an AI API to generate dynamic replies based on user queries.

Learn Spring AI

Spring AI is designed to make AI integration easy for Java developers. It works just like Spring Boot, so you will feel comfortable.

With Spring AI, you can:

Connect to AI models (like OpenAI)
Build chat-based applications
Handle prompts easily
Integrate embeddings and vector search

Example:

You can build a chatbot in your existing Spring Boot app that answers user questions about your product.

Simple use case:

A user types: “How do I reset my password?”

Your system sends this query to an AI model using Spring AI and returns a clean, human-like response.

Build Small Projects (Very Important)

Learning the theory aspect is not enough. You must build real applications.

Start with simple projects like:

AI Chatbot for FAQs
Resume Analyzer using AI
Email reply generator
Blog writing assistant

Example:

Supposing you’re running an e-commerce platform. You can build an AI feature where users ask:

“Suggest me shoes for running under ₹3000.”

And your system generates smart recommendations.

This is exactly what companies are doing today.

Learn Prompt Engineering

Prompt engineering means writing better inputs to get better outputs from AI.

Bad prompt:

“Tell me about Java.”

Good prompt:

“Explain Java in simple terms for beginners with real-world examples in 100 words.”

You will see a huge difference in output quality. As a Java developer, think of prompts like function inputs. Better input = better output.

Work with Data (Basic Level)

You don’t need deep data science knowledge, but you should know:

How to store and retrieve data
How to use vector databases
How embeddings work

Example:

If you build a document search system, you can store documents as embeddings and allow users to search using natural language.

User asks:

“Show me policies related to refunds.”

AI finds the most relevant content even if exact words don’t match.

Combine AI with Your Existing Skills

This is your biggest advantage.

You already know:

Spring Boot
Microservices
Security
Database handling

Now combine them with AI.

Example: In a banking app:

Use AI to detect fraud patterns
Generate automated customer responses
Summarize transaction history

You are not replacing your skills; you’re simply upgrading them.

Learn by Building Real Use Cases

Companies don’t hire AI engineers just for knowledge; they want problem solvers who focus on:

Solving real business problems
Building usable features
Creating end-to-end applications

Example:

Instead of just saying “I know AI,” build a project like:

“AI-powered ticket resolution system using Spring AI”

That’s what makes you stand out.

Keep It Simple and Consistent

Don’t try to learn everything at once.

Follow this path by:

Learning the basics of AI
Understanding APIs
Using Spring AI
Building projects
Improving step by step

Consistency matters more than speed.

Getting Started with Spring AI: A Simple Guide for Java Developers

Artificial Intelligence is becoming an important part of modern applications, but integrating AI into backend systems can feel complex. Different AI providers have different APIs, formats, and configurations, which makes development harder. This is where Spring AI helps Java developers.

Spring AI is a project from the Spring ecosystem that makes it easy to integrate AI into Java applications. It follows the same philosophy as Spring Boot. Instead of worrying about multiple AI APIs, Spring AI provides a consistent way to work with them. ( Medium)

What is Spring AI?

Spring AI is an extension of the Spring Framework designed to simplify working with AI models like chat models, embeddings, and image generation tools. It provides abstraction layers so that you don’t need to handle provider-specific complexity. ( Medium)

It allows you to connect your Java application with AI models easily, just like you connect a database using Spring.

Why Spring AI is Important

Before Spring AI, developers had to:

Write custom code for each AI provider
Handle different API formats
Manage complex integrations

Spring AI solves this by giving a unified API layer. You can switch between providers like OpenAI or others without changing much code. ( Home)

It also focuses on connecting your business data and APIs with AI models, which is the real need in modern applications. ( Home)

Core Components of Spring AI

Spring AI provides several important components that make development easy:

ChatClient: Which is used to build chatbots or conversational features
EmbeddingClient: Helps to convert text into vectors for search and recommendations
VectorStore: Stores embeddings for semantic search
PromptTemplate: Helps create dynamic and reusable prompts
Function Calling: Allows AI to call Java methods directly

These components provide a consistent programming model, regardless of which AI provider you use.

How Spring AI Works (Simple Flow)

User sends a request (Example: “Explain Java basics”)
Spring Boot controller receives the request
Spring AI processes it using prompts
It calls an AI model (like OpenAI)
The response is returned to the user

This flow is very similar to how you already build REST APIs, which makes it easy for Java developers to adopt.

How to Get Started

Starting with Spring AI is simple if you already know Spring Boot.

Step 1: Create a Spring Boot project

Go to Spring Initializr and add dependencies for Spring AI.

Step 2: Add dependencies

You can add Spring AI dependencies using Maven or Gradle. It is available in Maven Central, so setup is straightforward.

Step 3: Configure API keys

Add your AI provider API key (like OpenAI) in application.properties.

Step 4: Write a simple AI service

Use ChatClient to send prompts and get responses.

Example:

Create an endpoint like:

GET /ask?question=What is Spring Boot?

Your backend will send this to an AI model and return a clean response.

Real-World Use Cases

Spring AI is not just for demos. It is used in real applications:

Customer Support Chatbots

Automate responses for user queries in applications.

Document Q&A Systems

Users can ask questions about company policies or documents.

Smart Search Systems

Instead of keyword search, users can search in natural language.

Content Generation

Generate emails, reports, or product descriptions automatically.

An e-commerce app can use Spring AI to suggest products because the system understands intent and gives smart recommendations.

Advanced Features

Spring AI also supports advanced capabilities like:

Retrieval Augmented Generation (RAG) for using your own data
Chat memory for conversation-based apps
Multi-model support (text, image, audio)
Tool calling for executing backend logic

These features help build production-level AI systems, not just simple demos. ( Home)

Final Thoughts

Spring AI makes AI development simple for Java developers by removing unnecessary complexity. If you already know Spring Boot, you can start building AI-powered applications without learning a completely new ecosystem, and instead of switching to Python or learning heavy machine learning concepts, you can stay in Java and still build powerful AI features.

Start small, build a chatbot or a smart API, and then slowly move towards advanced use cases. That’s the best way to grow in AI with Spring AI.

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Originally published at https://blog.masteringbackend.com.

Mastering @RequestHeader in Spring Boot

Jane — Thu, 30 Apr 2026 10:00:30 +0000

Learn how to use @RequestHeader in Spring Boot to handle HTTP headers for authentication, metadata, and client information with practical real-world examples.

What is @RequestHeader

@RequestHeader is a Spring Boot annotation used to bind HTTP header values to method parameters in a controller. It is mainly used to handle metadata rather than core business data. For example, headers like Authorization, Content-Type, or User-Agent provide additional context about the request.

In real-world systems, it is commonly used for authentication (JWT tokens), request tracing (request IDs), and API versioning. It supports required, optional, and default values, making it flexible for different use cases. Proper use of headers improves API security, traceability, and communication between distributed systems.

@RequestHeader i s used in Spring Boot to extract values from HTTP request headers and bind them to method parameters, commonly for metadata like authentication tokens or client information in REST APIs.

In Spring Boot, @RequestHeader is used to extract values from HTTP request headers and bind them to method parameters. Headers usually contain metadata such as authentication tokens, content types, or client details.

Let’s start with a simple example:

@GetMapping("/api/data")
public String getData(@RequestHeader("User-Agent") String userAgent) {
    return "Client: " + userAgent;
}

When a request is made, Spring extracts the User-Agent header value and passes it to the method.

Now consider a real-world scenario where you need to validate an authentication token:

@GetMapping("/api/secure")
public String secureApi(@RequestHeader("Authorization") String token) {
    return "Token: " + token;
}

In production systems, this token is usually validated before processing the request.

You can also make headers optional:

@GetMapping("/api/info")
public String getInfo(
    @RequestHeader(value = "X-Request-Id", required = false) String requestId) {
    return "Request ID: " + requestId;
}

Or provide default values:

@GetMapping("/api/version")
public String getVersion(
    @RequestHeader(value = "version", defaultValue = "v1") String version) {
    return "API Version: " + version;
}

For multiple headers:

@GetMapping("/api/headers")
public String getHeaders(@RequestHeader Map<String, String> headers) {
    return headers.toString();
}

In Spring Boot, while @RequestHeader is commonly used to extract individual header values, you can also use HttpHeaders to handle multiple headers in a more flexible and scalable way. Let's look at a basic example:

@GetMapping("/headers/http-headers")
public String readHeaders(@RequestHeader HttpHeaders headers) {
    return "User-Agent: " + headers.get("User-Agent");
}

Here, the entire request header is mapped into a HttpHeaders object, allowing you to access any header dynamically. Now consider a real-world scenario where you want to track client information and location:

@GetMapping("/headers/http-headers")
public String readRequestHeadersWithHttpHeaders(
        @RequestHeader HttpHeaders requestHeaders) {

    return "Received: " 
        + requestHeaders.get("User-Agent") 
        + " " 
        + requestHeaders.get("User-Location");
}

Example request headers:

User-Agent: Chrome User-Location: India

This approach is very useful in production systems like microservices, where multiple headers such as Authorization, X-Request-Id, User-Agent, and custom headers are passed in every request.

In real-world applications like microservices or CRM systems, @RequestHeader is widely used for passing JWT tokens, tracking request IDs, handling API versioning, and managing client-specific data.

Best practices include validating sensitive headers like Authorization, avoiding overuse of headers for business data, and keeping header usage consistent across APIs.

Using @RequestHeader properly ensures secure, scalable, and well-structured APIs in production environments.

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Originally published at https://blog.masteringbackend.com.

Implementing Rate Limiting for AI APIs

Jane — Wed, 29 Apr 2026 10:00:30 +0000

Rate limiting is what keeps your APIs stable under pressure. It helps to control how many requests a user or system can make, especially when working with heavy AI models.

This guide walks through how API rate limiting works and how you can implement it in real-world systems. Exploring common strategies and learning how to handle the rate limit and errors helps you across different stacks.

How to Implement Rate Limiting in an API (Step by Step)

Step 1: Define what you want to limit

Start by selecting the key used to track requests. Which are usually:

IP address (simple, but less accurate)
User ID (better for authenticated systems)
API key (common for AI APIs)

For an AI system, API keys or user IDs give more control and fairness.

Step 2: Set a clear rate limit policy

Decide the number of requests you want within a particular time.

Examples:

100 requests per minute per user
1,000 requests per hour per API key

Keep the limits realistic. Most AI endpoints are often resource-heavy, so be sure to reduce the limits where necessary.

Step 3: Choose a rate-limiting algorithm

Make sure you pick a strategy based on your use case:

Fixed window: it’s simple, but can cause bursts at window edges
Sliding window: it gives smoother control over traffic
Token bucket: very flexible, and allows short bursts while enforcing limits

For most AI APIs, a token bucket or a sliding window works best.

Step 4: Save request counts efficiently

You need a fast storage layer that can help you track requests in real time.

Here are some common options:

In-memory store (Redis is widely used)
Application memory (only for single-instance apps)

Example Redis key:

rate_limit:user_123

Step 5: Intercept requests with middleware

Rate limiting should run before your main logic. In some frameworks, this is done using middleware, which helps to:

Extracts the identifier (IP, user ID, or API key)
Check the current request count
Decides whether to allow or reject a request

Step 6: Enforce the limit

If a request exceeds its limit, block it immediately by returning a standard HTTP response:

HTTP/1.1 429 Too Many Requests

Include helpful headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 60

This helps clients understand when they can retry.

Step 7: Handle allowed requests

If the request is within limits:

Increase the counter
Forward the request to the API handler

Keep this step fast. Rate limiting should not introduce noticeable latency.

Step 8: Add retry and backoff guidance

Clients should not retry immediately after hitting limits, encouraging exponential backoff helps to reduce pressure on your API during spikes.

Step 9: Log and monitor rate limit activity

Be sure to track:

The number of blocked requests
The most active users or API keys
The patterns of abuse

This will help to fine-tune limits and detect misuse early.

Step 10: Test under load

Simulate high traffic before deploying, and be sure to check:

Whether limits are enforced correctly
If legitimate users are blocked too early
How the system behaves under burst traffic

Rate limiting should protect your API without breaking normal usage.

Implementing Rate Limiting in C-Based APIs

C-based APIs mostly run on high-performance environments where efficiency matters. For this, rate limiting needs to be fast, memory-conscious, and thread-safe by making sure to choose a lightweight tracking mechanism.

In C, this is usually done with:

in-memory hash tables
shared memory (for multi-process setups)
external stores like Redis (for distributed systems)

Defining a rate limit structure

Create a struct to track request counts and timing:

typedef struct {
    int request_count;
    time_t window_start;
} RateLimit;

Map the key as an IP address or API key.

Use a hash table for fast lookups, and each incoming request should:

Extract the identifier (IP or API key)
Look up its rate limit record
Update or reset the counter

Example using pseudo-hash map logic:

RateLimit* rl = get_rate_limit(key);

if (current_time - rl->window_start > WINDOW_SIZE) {
    rl->request_count = 1;
    rl->window_start = current_time;
} else {
    rl->request_count++;
}

Check the count before processing the request:

if (rl->request_count > MAX_REQUESTS) {
    return 429; // Too Many Requests
}

Avoid heavy operations in this path.

C-based APIs often run in multi-threaded or multi-process environments, and the race conditions can break rate-limiting logic.

Use:

mutex locks (for threads)
atomic operations (for counters)
shared memory locks (for multi-process systems)

Example with a mutex:

pthread_mutex_lock(&lock);
/* update rate limit */
pthread_mutex_unlock(&lock);

Keep lock duration short to avoid performance bottlenecks.

Each active user or IP consumes memory, and without cleanup, the memory usage grows over time.

Implement expiration:

remove entries after inactivity
periodically clean old records

This prevents memory leaks in long-running services.

Use Redis for distributed rate limiting

If your C API runs across multiple servers, in-memory tracking is not going to be enough.

Use Redis with atomic operations:

INCR rate_limit:user_123
EXPIRE rate_limit:user_123 60

This ensures consistent limits across all instances.

In C environments, simplicity often wins.

Fixed window: easiest to implement
Token bucket: better for handling bursts

A token bucket can be implemented with a counter that refills over time.

Return proper HTTP responses

Even in C-based servers, follow standard responses:

HTTP/1.1 429 Too Many Requests

Be sure to include headers for better client handling

C systems are often used for high-throughput APIs to help simulate:

burst traffic
concurrent requests
edge cases around time windows

Efficient rate limiting in C rests on tight control rather than memory, concurrency, and execution time. If implemented correctly, it protects your API without slowing it down.

Adding Rate Limiting to Python and FastAPI Services

Rate limiting in Python APIs is normally implemented at the middleware or dependency level. For FastAPI, this approach keeps the logic centralized and easy to reuse across routes.

For most AI APIs, API keys or user IDs give better control than IP-based limits.

Instead of trying to build everything from scratch, use proven tools like slowapi or fastapi-limiter, and integrate them directly with FastAPI and reduce implementation complexity.

Example using fastapi-limiter with Redis:

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi_limiter import FastAPILimiter
from fastapi_limiter.depends import RateLimiter
import aioredis

app = FastAPI()

@app.on_event("startup")
async def startup():
    redis = await aioredis.from_url("redis://localhost")
    await FastAPILimiter.init(redis)

@app.get("/chat", dependencies=[Depends(RateLimiter(times=5, seconds=60))])
async def chat_endpoint():
    return {"message": "Request allowed"

This limits requests to 5 per minute per client and each request:

Extracts a unique identifier
Stores or increments a counter in Redis
Checks if the limit is exceeded
Blocks or allows the request

Redis is mostly used because it supports atomic operations and works well in distributed systems.

Example:

@app.get("/inference", dependencies=[Depends(RateLimiter(times=10, seconds=60))])

This keeps resource-heavy endpoints protected.

When a limit has been exceeded, FastAPI automatically returns:

429 Too Many Requests

You can customize the response:

@app.exception_handler(429)
async def rate_limit_handler(request: Request, exc):
    return JSONResponse(
        status_code=429,
        content={"detail": "Rate limit exceeded. Try again later."},
    )

If you want a global limit across all routes, applying middleware instead of per-route dependencies works, and it ensures every request passes through the same rate-limiting logic.

In production, most FastAPI apps often run with multiple workers, which may stop in-memory counters from syncing across instances.

Always use a shared store like Redis for:

consistent limits
distributed deployments
horizontal scaling

FastAPI makes rate limiting straightforward when combined with Redis and middleware patterns. The most important part is keeping it efficient, consistent, and aligned with how your API is being used.

Have a great one!!!

Author: Toluwanimi Fawole

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Originally published at https://blog.masteringbackend.com.

Mastering @RequestParam in Spring Boot

Jane — Tue, 21 Apr 2026 09:00:00 +0000

Learn how to use @RequestParam in Spring Boot to handle query parameters effectively with practical examples from real-world scenarios like search, filtering, and pagination.

What is `@RequestParam`

@RequestParam is a Spring Boot annotation used to bind query parameters from the URL to method parameters in a controller. Unlike @PathVariable, which is used for identifying resources, @RequestParam is mainly used for filtering, searching, and optional data inputs.

@RequestParam is used in Spring Boot to extract query parameters from the URL and bind them to method parameters for filtering, searching, or optional inputs in REST APIs.

For example, /products?category=books&price=500 uses query parameters to filter results. It is widely used in real-world applications like e-commerce for search functionality, pagination, and sorting. It also supports optional values, default values, and multiple inputs. This makes APIs more flexible without changing the endpoint structure, improving usability and scalability in production systems.

In Spring Boot, @RequestParam is used to extract values from query parameters in the URL. It is commonly used when you want to pass optional or filtering data to your APIs without changing the URL structure.

Let’s start with a simple example:

@GetMapping("/users")
public String getUserById(@RequestParam Long userId) {
    return "User ID: " + userId;
}

Use our Online Code Editor

When a request like /users?userId=101 is made, Spring maps 101 to the userId parameter.

Now consider a real-world e-commerce scenario where users search for products:

@GetMapping("/products")
public String searchProducts(@RequestParam String category,
                             @RequestParam String sortBy) {
    return "Category: " + category + ", Sort By: " + sortBy;
}

Use our Online Code Editor

Example request: /products?category=electronics&sortBy=price

You can also make parameters optional:

@GetMapping("/products")
public String getProducts(@RequestParam(required = false) String category) {
    return "Category: " + category;
}

Use our Online Code Editor

Or provide default values:

@GetMapping("/products")
public String getProducts(
    @RequestParam(defaultValue = "all") String category) {
    return "Category: " + category;
}

Use our Online Code Editor

For multiple values:

@GetMapping("/products/filter")
public String filterProducts(@RequestParam List<String> tags) {
    return "Tags: " + tags;
}

Use our Online Code Editor

In real-world systems like CRM or booking platforms, @RequestParam is used for filtering data such as date ranges, status, pagination (page, size), or sorting options.

Best practices include keeping query parameters meaningful, using default values for better UX, validating inputs, and avoiding too many parameters in a single API.

Using @RequestParam properly helps build flexible, scalable, and user-friendly APIs aligned with REST standards.

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Difference Between OpenAI API Key and Azure OpenAI API Key

Jane — Mon, 20 Apr 2026 09:00:00 +0000

Developers can access AI models using two main platforms:

OpenAI
Azure OpenAI

Both provide access to similar AI models, but the way authentication and deployment work is different.

In this article, we will understand the difference between OpenAI API keys and Azure OpenAI API keys.

OpenAI API Key

OpenAI provides direct access to AI models through its own platform.

Developers can sign up on the OpenAI website and generate an API key.

Example platform:

https://platform.openai.com

Steps to Get OpenAI API Key

Login to OpenAI platform.
Go to API Keys.
Click Create New Secret Key.

Example:

sk-xxxxxxxxxxxxxxxxxxxxxxxx

Use our Online Code Editor

This key can be used directly with OpenAI APIs.

Example endpoint:

https://api.openai.com/v1/chat/completions

Use our Online Code Editor

Azure OpenAI API Key

Azure OpenAI provides OpenAI models through Microsoft Azure infrastructure.

Instead of using OpenAI servers directly, the requests go through Azure services.

Azure OpenAI requires:

Azure resource
Model deployment
Endpoint
API key

Example API Key:

xxxxxxxxxxxxxxxxxxxxxxxx

Use our Online Code Editor

Example Endpoint:

https://openai-demo.openai.azure.com/

Use our Online Code Editor

Key Differences

OpenAI API

Hosted by OpenAI
Direct API usage
Simple setup
Single endpoint

Azure OpenAI

Hosted on Microsoft Azure
Requires resource creation
Requires model deployment
Uses Azure endpoint

When to Use OpenAI

Use OpenAI when:

You want quick setup
You are building prototypes
You want direct API access

When to Use Azure OpenAI

Use Azure OpenAI when:

You need enterprise security
You want Azure integration
Your organization already uses Azure cloud
You need regional deployment

Conclusion

Both OpenAI and Azure OpenAI provide access to powerful AI models.

OpenAI is easier for quick development, while Azure OpenAI is better suited for enterprise applications that require scalability, security, and integration with other Azure services.

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

How to Create an Azure OpenAI Resource and Deploy Your First Model.

Jane — Fri, 17 Apr 2026 09:00:00 +0000

Azure OpenAI allows developers to use powerful AI models such as GPT-4, GPT-4o, and GPT-3.5 directly from the Azure cloud. These models can be used to build chatbots, AI assistants, content generators, and many intelligent applications.

In this article, you will learn how to create an Azure OpenAI resource, deploy a model, and get the API key required to use the service in your application.

Prerequisites

Before starting, make sure you have:

An Azure account
Access to the Azure Portal
Azure OpenAI service is enabled for your subscription

If you do not have an Azure account, you can create one from the Azure website.

Step 1: Create Azure OpenAI Resource

First, you need to create an Azure OpenAI resource.

Open the Azure Portal:

https://portal.azure.com

Steps

Login to the Azure Portal.
In the search bar, type Azure OpenAI.
Click Create.

Now fill the required fields.

Configuration

Resource Group

Create a new resource group or select an existing one.

Region

Choose a supported region such as:

East US
Sweden Central

Name

Enter a unique resource name.

Example:

openai-demo

Use our Online Code Editor

Pricing Tier

Select Standard.

After filling the details:

Click Review + Create

Then click Create to deploy the resource.

Deployment usually takes around one to two minutes.

Step 2: Deploy a Model

Once the resource is created, you need to deploy a model.

Steps

Open the Azure OpenAI resource you created.
In the left menu, click Model Deployments.
Click Deploy Model.

Now select a model.

Recommended Models

For most applications, these models work well:

gpt-4o-mini

Fast and cost efficient model.

gpt-35-turbo

Popular chat model.

Deployment Configuration

Model

Select the model you want.

Deployment Name

Example:

gpt-4o-mini

Use our Online Code Editor

Click Deploy.

Azure will now create the model deployment.

Step 3: Get API Credentials

To call the Azure OpenAI API from your application, you need an API key and endpoint.

Steps

Open the Azure OpenAI resource.
Click Keys and Endpoint.

You will see the following information.

API Key 1

API Key 2

Endpoint

Example:

API KEY
xxxxxxxxxxxxxxxxxxxxxxxx

ENDPOINT
https://openai-demo.openai.azure.com/

Use our Online Code Editor

You can use either Key 1 or Key 2 in your application.

Example API Endpoint

Your application will send requests to the endpoint.

Example:

https://openai-demo.openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2024-02-15-preview

Use our Online Code Editor

Your request must include:

API Key
Endpoint
Deployment Name

Conclusion

Azure OpenAI makes it easy to use powerful AI models in enterprise applications. The basic process involves three steps:

Create an Azure OpenAI resource
Deploy a model such as gpt-4o-mini
Get API credentials and endpoint

Once these steps are completed, you can start building AI-powered applications using Azure OpenAI.

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Mastering @PathVariable in Spring Boot

Jane — Thu, 16 Apr 2026 10:00:30 +0000

Learn how to use @PathVariable in Spring Boot to build clean and RESTful APIs with practical examples from real-world scenarios like users, products, and orders.

What is `@PathVariable`

@PathVariable in Spring Boot is an annotation used to bind values from the URL directly to method parameters in a controller. It is mainly used in REST APIs where resources are identified using hierarchical URLs. For example, in /users/101, the value 101 represents a specific user and is captured using @PathVariable.

@PathVariable is used in Spring Boot to extract values from the URL path and bind them to method parameters to identify specific resources in REST APIs.

It differs from query parameters because it is part of the URL path, making APIs more readable and meaningful. In real-world systems like e-commerce or CRM, it is commonly used to fetch specific records, such as a user, product, or order, by ID. It also supports multiple values and even dynamic mapping using a Map structure when needed.

In Spring Boot, @PathVariable is used to extract dynamic values from the URL. It helps in designing RESTful APIs where resources are clearly identified using URL paths instead of query parameters.

Let’s start with a simple example:

@GetMapping("/users/{userId}")
public String getUser(@PathVariable Long userId) {
    return "User ID: " + userId;
}

Use our Online Code Editor

When a request like /users/101 is made, Spring automatically maps 101 to the userId variable.

Now consider a real-world scenario in an e-commerce system where a user wants to view a specific product:

@GetMapping("/users/{userId}/products/{productId}")
public String getUserProduct(@PathVariable Long userId,
                             @PathVariable Long productId) {
    return "User: " + userId + ", Product: " + productId;
}

Use our Online Code Editor

This makes the API intuitive and readable.

You can also customize variable names:

@GetMapping("/users/{userId}/orders/{orderId}")
public String getOrder(@PathVariable(name = "userId") Long id,
                       @PathVariable Long orderId) {
    return "User: " + id + ", Order: " + orderId;
}

Use our Online Code Editor

For dynamic cases, you can use a Map:

@GetMapping("/users/{userId}/address/{addressId}")
public String getAddress(@PathVariable Map<String, String> pathVars) {
    return "User: " + pathVars.get("userId") +
           ", Address: " + pathVars.get("addressId");
}

Use our Online Code Editor

This is useful when handling flexible URLs.

In real-world applications like CRM or booking systems, @PathVariable is used to fetch user details, order history, or product information based on unique identifiers.

Best practices include using meaningful variable names, avoiding too many path variables in one endpoint, and validating inputs properly. Also, prefer strongly typed variables over Map when possible.

Using @PathVariable correctly improves API clarity, maintainability, and aligns with REST standards followed in production-grade applications.

Have a great one!!!

Author: Ayush Shrivastava

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

TOP 5 Books Every Backend Developer Should Read

Jane — Fri, 10 Apr 2026 10:00:30 +0000

The world of software development is fast-paced. If you glance away to pet your cat too long, you may miss the next big framework or tool. For instance, JavaScript, one of the most popular programming languages in the world, is notorious for pushing out new frameworks as often as a developer has a bad day , which happens more often than you may think. Because of this, many developers need to get information quickly, and the best mediums to get that information come in the form of short-form videos, quick articles, and snappy courses. While we can appreciate the roles these play in keeping us up to speed with development trends, it’s still crucial to settle in with a good book once in a while.

Some development books may seem intimidating judging by volume alone, but the treasures they hold within are timeless. Usually, what separates good developers from average developers is how much time they are willing to read between the lines and understand the underlying concepts that run programs, so they can be more efficient at solving problems. If you’d like to be the best backend developer you could be, have a look at these top five books backend developers should read that’ll be sure to take you to the next level of your career.

1. Designing Data-Intensive Applications by Martin Kleppmann

This book is a classic for those seeking to understand how data works and is handled by applications. It dives into ways to optimize data, so you produce programs that retrieve and use data quickly and efficiently.

Here, you’ll be looking into database storage and trade-offs that exist between different data technologies. It introduces these core trade-offs in distributed systems like consistency, availability, and scalability, which shape how real-world backend systems are designed. As a backend developer, dealing with data constantly, this book is a must-have and will help you explore the fundamental principles of data systems.

2. Clean Code by Robert C. Martin

Clean code is a tricky subject. After a few years in development, you realize that there are certain standards that must be upheld in your code, but you also become aware that these same standards and best practices are not set in stone and may be broken on occasion. An example is the DRY principle. You may know that repeating code is bad practice, but would you stick to this rule so much, at the expense of readable code? That’s where Clean Code by Robert C. Martin saves the day. It dives into such questions and explains what it truly means for code to be clean.

Robert’s book emphasizes that writing clean code isn’t about unbending rules, but about making thoughtful decisions in matters of readability, maintainability, and practicality.

You’ll learn about writing code that is self-documenting, keeping functions focused on one thing and other such rules for maintainable, readable and modular code. Rid yourself of code smells, and get a copy.

3. Cracking the Coding Interview by Gayle Laakmann McDowell

Coding interviews are not a walk in the park. In some cases, the questions you may face in a technical interview may seem quite abstract and sometimes a bit different from what you deal with at work in your day-to-day. If you’re thinking of taking a bold step into job searching, this book is a classic and a must-have in your preparation attempts.

Beyond just practicing interview questions, it’ll help you build a problem-solving mindset. Solve over 180 coding questions and find yourself walking confidently in and out of technical interviews.

4. Fundamentals of Software Architecture by Richard and Ford

This book is a haven for those seeking a good introduction to Software Architecture fundamentals. It discusses eight architectural styles, each with detailed explanations. It explains how different architectural styles impact system performance, scalability, and maintainability, which are key concerns in backend development. It could serve as a great handbook and source material for all things architecture-related.

5. Grokking Algorithms by Aditya Bhargava

This book is a delight. It makes algorithms easier to follow and visual learners would benefit greatly from the illustrations. In it, Aditya simplifies concepts like Big O Notation, recursion and dynamic programming.

On reading this book, you’ll realize soon enough that it makes complex algorithmic concepts intuitive, helping developers understand not just how solutions work, but why they work. The author makes these rather abstract concepts easier to mentally navigate with his witty and brilliant writing.

Conclusion

The above are just a few of many interesting and amazing books that will keep you deeply engaged. While some of the books on this list aren’t specifically targeted at backend developers, they are great to have in your library as they concern general coding best practices and critical thinking.

Why not pick up a book today? Perhaps lose yourself in the whimsical world of Grokking Algorithms, be amazed by how Martin Kleppman explains the secret recipes needed in designing data-intensive applications, or carefully observe and craft your methods after reading Robert C. Martin’s Clean Code.

Have a great one!!!

Author: Amanda Ene Adoyi

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Originally published at https://blog.masteringbackend.com.

Persistent Chat History with Database Design (Practical Example)

Jane — Thu, 09 Apr 2026 10:00:30 +0000

Chat applications look simple on the surface when you look at them. But behind every smooth conversation, there is a system that stores, retrieves, and manages messages efficiently.

What makes modern apps usable is the persistent chat history. A lot of users would expect conversations to load instantly, stay in order, and remain available across all their devices; that only works when the database design is done in the right way.

This guide focuses on how persistent chat history works in a real system, and how conversations, users, and messages are structured step by step to keep your application responsive, organized, and ready for real-world use.

Example Schema for a Chat Application

To ensure you have a strong chat schema, you must begin with three main entities: users, conversations, and messages. Keeping these entities separate makes the system easier to scale, query, and maintain.

At the very least, you need a users table or collection that helps store identity and basic profile data.

{
  "user_id": "u123",
  "username": "john_doe",
  "created_at": "2026-01-01T10:00:00Z"
}

Next is the conversations entity , which represents the chat thread between two or more users. It acts as the container for messages.

{
  "conversation_id": "c456",
  "participants": ["u123", "u789"],
  "created_at": "2026-01-01T10:05:00Z"
}

This structure allows group chats and one-on-one chats without changing the schema.

The most important part is the messages entity. Each message belongs to a conversation and a sender, which is where most queries will happen, and it’s meant to be designed carefully.

{
  "message_id": "m001",
  "conversation_id": "c456",
  "sender_id": "u123",
  "content": "Hello, how are you?",
  "timestamp": "2026-01-01T10:06:00Z"
}

Always include a timestamp; the ordering of the message depends on it. Also, having a relational database can be translated into three tables:

users (user_id, username, created_at)
conversations (conversation_id, created_at)
messages (message_id, conversation_id, sender_id, content, timestamp)

A joint table like conversation_participants is always needed to map users to conversations:

This helps to avoid duplicating participant data and keeps relationships flexible.

Create indexes on:

conversation_id i n the messages table for fast retrieval
timestamp for ordered queries
sender_id for filtering user messages

Not having a proper index can lead to the chat queries slowing down quickly as soon as data grows.

And for NoSQL databases like MongoDB, you can use a similar structure with collections:

users
conversations
messages

Or you can embed messages inside conversations for smaller apps:

{
  "conversation_id": "c456",
  "participants": ["u123", "u789"],
  "messages": [
    {
      "sender_id": "u123",
      "content": "Hello",
      "timestamp": "2026-01-01T10:06:00Z"
    }
  ]
}

Embedding works well for smaller volume chats. For high-scale systems, you’ll need to separate message collections to improve performance.

Add optional fields to support real-world features:

status (sent, delivered, read)
edited_at (for message edits)
deleted_at (for soft deletes)
attachments (for media support)

Keeping the schema flexible is important, but try as much as possible to avoid overloading it early. Start simple and extend only when needed.

Sample Data Model for Conversations and Messages

Having a good data model defines how conversations and messages relate, how they are queried, and how they scale under load.

Start with a conversation-centric model. Every message belongs to a conversation, and every conversation has participants.

Example:

{
  "conversation_id": "c001",
  "type": "group",
  "participants": ["u1", "u2", "u3"],
  "last_message_id": "m045",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:10:00Z"
}

The last_message_id is important because it allows quick previews without scanning all the messages, and that is how chat lists load fast in real apps.

Let’s now define the message model. Each message is stored independently and linked to its conversation.

{
  "message_id": "m045",
  "conversation_id": "c001",
  "sender_id": "u2",
  "content": "Let’s deploy today",
  "timestamp": "2026-01-01T10:09:00Z",
  "status": "delivered"
}

Avoid updating message content frequently; it keeps the system predictable.

Add a sequence or ordering field when strict ordering is required.

"sequence": 45

Timestamps can collide in high-throughput systems, and a sequence number guarantees correct ordering, especially in distributed setups.

For relational databases, the model translates into:

conversations
messages
participants

Each table has a clear role. Queries stay simple and efficient.

Example:

SELECT * FROM messages
WHERE conversation_id = 'c001'
ORDER BY timestamp ASC
LIMIT 50;

In NoSQL systems, the model is somewhat similar but optimized for access patterns. Messages stay in a separate collection for scalability, and conversations store lightweight metadata only.

For high-performance systems, denormalization helps to store frequently accessed data, such as:

last message content
unread message count
last active timestamp

directly in the conversation object.

{
  "conversation_id": "c001",
  "last_message": "Let’s deploy today",
  "unread_count": {
    "u1": 2,
    "u3": 1
  }
}

This avoids expensive joins or aggregations during reads.

Designing for pagination from the start is very important. Offset-based pagination tends to break at scale. Use cursor-based pagination instead, typically with timestamp or message_id.

GET /messages?conversation_id=c001&before=m045&limit=20

This keeps queries fast even with millions of messages.

Also, support additional fields without breaking the model:

attachments for media
reply_to for threaded replies
metadata for AI-generated context or tags

Having a clean data model balances structure and flexibility. When conversations and messages are modeled correctly, the performance, scaling, and feature development become easier to manage.

Writing and Reading Chat Messages Step by Step

Writing and reading chat messages are meant to be simple, fast, and consistent. Every step taken must be predictable, especially when under high traffic.

When a user sends a message, the system receives a request with key fields like conversation_id, sender_id, and content. It validates these inputs first, then rejects empty messages or invalid conversation IDs early.

It also generates a unique message_id. which can be a UUID or a database-generated ID, and also attaches a timestamp and, if needed, a sequence value for strict ordering.

{
  "message_id": "m101",
  "conversation_id": "c001",
  "sender_id": "u1",
  "content": "Message received",
  "timestamp": "2026-01-01T10:15:00Z"
}

Then insert the message into the database.

In a relational database, wrap it in a transaction if multiple tables are updated, while in NoSQL systems, ensure the write is acknowledged before proceeding. Be sure to update the conversation metadata immediately after.

This typically includes:

last_message_id
last_message optional preview
updated_at timestamp

This ensures that the chat lists reflect the latest activity without querying the messages table.

Example:

UPDATE conversations
SET last_message_id = 'm101',
    updated_at = NOW()
WHERE conversation_id = 'c001';

If the system supports unread counts, then the increment counters for other participants. This helps to reduce the recalculating counts during reads.

The most common operation is fetching messages for a conversation. Always send a query using conversation_id and sort by timestamp or sequence.

SELECT * FROM messages
WHERE conversation_id = 'c001'
ORDER BY timestamp DESC
LIMIT 20;

Make use of pagination and never load all messages at once.

Cursor-based pagination works best at scale. Instead of offsets, be sure to use a reference point like message_id or timestamp.

GET /messages?conversation_id=c001&before=2026-01-01T10:15:00Z&limit=20

This keeps performance stable even with a large dataset.

Be sure to reverse the result set on the client if needed. Most databases tend to return recent messages first for efficiency.

After writing a message, publish an event (via WebSocket or message queue). It helps to push new messages to connected clients without polling the database.

Ensure that writes are visible to reads immediately or within an acceptable delay. Efficient write and read paths are the pillar of any chat system. If any of these steps are optimized, the whole messaging experience feels instant and reliable even as the data grows.

Optimizing Queries for Real-Time Chat Apps

Real-time chat performance depends heavily on how the queries are written and how they are being executed. Slow queries lead to delayed messages, laggy interfaces, and poor user experience.

The most important query in any chat app is fetching messages by conversation_id. Without an index, this becomes a full table or collection scan.

Create indexes on:

Example, in SQL:

CREATE INDEX idx_conversation_timestamp
ON messages (conversation_id, timestamp DESC);

This allows fast retrieval of recent messages without scanning the entire dataset.

Only select the fields needed for rendering messages. Pulling large payloads (like attachments or metadata) when not required increases latency and memory usage.

Smaller result sets mean faster queries.

Offset queries tend to slow down as data grows because the database still scans skipped rows.

Bad approach:

LIMIT 20 OFFSET 10000;

Better approach:

WHERE timestamp < '2026-01-01T10:15:00Z'
ORDER BY timestamp DESC
LIMIT 20;

This keeps the performances consistent, even with millions of messages.

Chat lists and recent messages are requested often. Use in-memory stores like Redis to cache:

Last messages per conversation
unread counts
active conversation lists

This reduces the database load and improves the response time.

Instead of joining multiple tables for every request, store frequently needed fields directly in the conversation record, and if multiple conversations need to be loaded, fetch them in a single query instead of multiple round-trip requests.

Always filter by conversation_id or user context. Unbounded queries tend to increase load and expose unnecessary data.

A query that works with 1,000 messages may fail at 1 million. So be sure to simulate large datasets early to identify bottlenecks before they reach production.

When queries are optimized, messages load instantly, scrolling feels smooth, and the system scales without you constantly rewriting it.

Have a great one!!!

Author: Toluwanimi Fawole

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Originally published at https://blog.masteringbackend.com.

Authentication & Session Management for AI Apps

Jane — Wed, 08 Apr 2026 10:00:30 +0000

AI applications don’t just help to process data; they interact with users, agents, and external services. This could either be a human user logging into a chatbot or an AI agent calling another service. Without having proper authentication, AI APIs become vulnerable to misuse or unauthorized access.

When users log into an AI-powered product, the system needs to verify identity, manage access permissions, and maintain conversation or activity sessions, which is important for AI apps that handle chat interactions, autonomous agents, or high-volume API requests.

This guide breaks down how authentication works in AI applications and how to manage sessions securely at scale.

API Key Authentication for AI Services

API key authentication is one of the most common ways to secure AI services and machine learning APIs, and it works by assigning a unique key to each client, application, or developer account. Every request sent to the AI service must include the key so the server can verify access.

The API key acts as a simple credential, and when a request reaches the server, the service checks the key against the stored records. If the key is valid, the request proceeds to the AI model or processing pipeline.

A typical example looks like this:

POST /v1/inference
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Some APIs accept the key through a custom header:

x-api-key: YOUR_API_KEY

Once it has been verified, the service processes the request and returns the model output.

API keys are widely used in AI platforms because they are very easy to generate, distribute, and revoke. This makes them a practical option for developer-facing AI services, internal microservices, and early-stage AI products.

They are mostly common in:

Machine learning inference APIs
AI-powered developer platforms
internal AI microservices communicating with each other
automation tools that interact with AI endpoints

Security practices matter a lot when using API keys. Keys should never be stored in client-side code or a public repository. Exposing a key in frontend JavaScript or committing it to version control makes it easy for attackers to copy and misuse.

Instead of doing that, store the keys in environment variables or secure a configuration system whereby whenever a backend service needs the key, it retrieves it from the environment rather than hardcoding it.

Key rotation is very important; generating new keys and deactivating old ones reduces long-term risk if a credential leaks. And if a compromised key suddenly generates thousands of requests per minute, the system should throttle or temporarily block the activity.

Despite their simplicity, API keys have limitations, and they identify the calling application but do not inherently represent a user identity or permission scope, simply because a lot of production AI platforms combine API keys with additional security layers such as usage quotas, IP restrictions, or token-based authentication.

But when implemented correctly, API key authentication helps to provide an effective way to secure AI services while also keeping integration simple for developers.

Token-Based Authentication Using JWT

Token-based authentication is mostly used in modern AI APIs and applications. Instead of you sending login credentials with every request, the system issues a token after the user successfully authenticates, and one of the most common formats is a JSON Web Token (JWT).

A JWT is more like a compact URL-safe token that contains encoded information about the authenticated identity. It includes user details, permissions, and an expiration timestamp. The token is digitally signed just so the server can verify its authenticity without it needing to store session data.

Some typical examples of JWT authentication workflow are:

When a user or service sends login credentials to an authentication endpoint.
When the server verifies the credentials.
When the server generates a signed JWT.
When the client includes the token in future requests to protected endpoints.

Most APIs expect the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

When a request reaches the AI service, the backend verifies the token signature and checks its expiration time. If the token is valid, then the request proceeds to the AI model or application logic.

JWT tokens are mostly used in AI platforms that support user accounts, dashboards, or role-based access control.

JWTs consist of three parts separated by periods:

HEADER.PAYLOAD.SIGNATURE

The header describes the signing algorithm
The Payload contains claims such as user ID, role, and expiration time
The Signature verifies that the token was issued by a trusted authority

Simply because the token is signed, the server can verify it without storing session data in a database, which makes JWT authentication stateless, ideal for scalable AI systems and microservice architectures.

Stateless authentication helps to simplify horizontal scaling when multiple AI API instances are running behind a load balancer; any instance can validate the token without needing shared session storage.

JWTs typically include an exp claim that helps to define when the token becomes invalid. Short-lived tokens reduce security risk if a token is intercepted or leaked.

A lot of systems also issue refresh tokens. When an access token expires, the refresh token can request a new one without forcing the user to log in again. When using JWT authentication, security best practices are important

Always sign tokens using strong algorithms such as HS256 or RS256. Never trust an unsigned token or a token created on the client side.

Sensitive information should not be stored inside the token payload. Even though JWTs are signed, they are not encrypted by default.

For web applications, storing tokens in secure HTTP-only cookies helps reduce exposure to cross-site scripting attacks.

In AI applications, JWT authentication works well for:

AI dashboards with authenticated users
Multi-tenant AI platforms
AI-powered APIs that enforce user roles
Microservices communicating with each other

When implemented correctly, JWT-based authentication provides a scalable and secure identity mechanism for modern AI applications while also keeping request handling fast and stateless.

OAuth and Social Login for AI Platforms

In AI platforms, OAuth and social login simplify account management while improving security.

Instead of storing passwords directly, the AI application helps by delegating authentication to an external provider. Common providers include Google and GitHub. The application receives a secure access token that verifies the user’s identity.

A typical OAuth flow looks like this:

A user clicks a social login option (for example, “Sign in with Google”).
The application redirects the user to the identity provider.
The provider verifies the user’s identity.
The provider returns an authorization token to the AI platform.
The AI application creates a session or issues its own internal access token.

This approach helps to remove the need to manage passwords directly. Password storage introduces security responsibilities like hashing, credential rotation, and breach mitigation. OAuth helps to shift those responsibilities to specialized identity providers.

OAuth is useful for AI platforms that target developers or teams. Take for example, an AI code assistant might allow developers to log in using GitHub accounts, and once authenticated, the platform can securely access repository metadata or integrate with development workflows.

OAuth supports scopes that help define exactly what an application is allowed to access. Instead of granting full account control, a user might allow an AI app to read profile data or access specific resources.

OAuth also helps to improve onboarding speed. Users can sign in with existing accounts in seconds instead of filling out registration forms, which helps to reduce friction, particularly important for consumer AI applications.

When implementing OAuth, security practices still matter. Always validate authorization tokens on the backend server and never rely solely on client-side verification. It is important to store minimal identity information locally, and in most cases, the AI platform only needs a unique user ID and basic profile data from the identity provider.

For AI systems that interact with external services, OAuth can also enable secure API integrations. The same goes for AI platforms with user accounts, dashboards, or collaborative tools. OAuth and social login provide a secure and scalable authentication method while also reducing the complexity of managing passwords internally.

Passwordless Authentication for AI Apps

Passwordless authentication helps users to access an AI application without you creating or entering a traditional password. What it does is, the system verifies identity using alternatives such as magic links, one-time passcodes (OTP), biometric authentication, or hardware security keys.

This approach is becoming very popular because passwords are now a major security weakness. Removing passwords reduces risks like credential reuse, phishing, and weak password selection.

For example, a common workflow uses email magic links:

The user enters an email address.
The AI application generates a temporary login link.
The link is sent to the user’s email.
Clicking the link verifies identity and creates a session.

Another common method used is a one-time passcode sent through email, SMS, or an authenticator app. The user enters the code within a short time window, and the system validates it before granting access.

These methods work well for AI platforms that prioritize fast onboarding, removing the need to create and remember passwords, which reduces friction and can improve user adoption for consumer-facing AI tools.

Passwordless authentication is useful for:

AI chat platforms
AI productivity tools
developer-facing AI dashboards
internal AI tools used by teams

Modern passwordless systems often rely on WebAuthn or FIDO2 standards. These technologies support biometric authentication through devices such as fingerprint scanners or facial recognition built into phones and laptops. Instead of transmitting a password, the device verifies the user locally and signs a cryptographic challenge.

This provides strong protection against phishing attacks because authentication is tied to the user’s device and domain.

Developers building AI applications should also consider session handling after authentication succeeds. Even without passwords, the system still needs a secure session token or an access token to maintain the user’s authenticated state during API requests.

Passwordless authentication offers a secure and user-friendly approach for AI applications, as it tends to reduce credential risks while keeping login flows simple for users interacting with modern AI services.

Have a great one!!!

Author: Toluwanimi Fawole

Thank you for being a part of the community

Before you go:

Whenever you’re ready

There are 4 ways we can help you become a great backend engineer:

The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges.
The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers.
Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer.
Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board.

Originally published at https://blog.masteringbackend.com.