<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Balmik Prajapati  on Medium]]></title>
        <description><![CDATA[Stories by Balmik Prajapati  on Medium]]></description>
        <link>https://medium.com/@balmikprajapati53?source=rss-681587818157------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*8ND1hJbneKOVi4NHQdgGUA.jpeg</url>
            <title>Stories by Balmik Prajapati  on Medium</title>
            <link>https://medium.com/@balmikprajapati53?source=rss-681587818157------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 01:39:51 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@balmikprajapati53/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The 5 Stages of AI Adoption: From Gated to AI-Native]]></title>
            <link>https://medium.com/@balmikprajapati53/the-5-stages-of-ai-adoption-from-gated-to-ai-native-e5f80da50b09?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/e5f80da50b09</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Wed, 12 Aug 2026 12:31:06 GMT</pubDate>
            <atom:updated>2026-08-12T12:31:06.924Z</atom:updated>
            <content:encoded><![CDATA[<h3>Why “Are we using AI?” is the wrong question — and what to ask instead</h3><p>Most teams treat AI adoption like a light switch. On or off. Allowed or blocked. Modern or behind.</p><p>But that’s not how it actually plays out.</p><p>Adoption moves in stages — and it moves for a reason. What a team cares about changes as trust grows. First you care about <strong>control</strong>. Then <strong>speed</strong>. Then <strong>coordination</strong>. Then <strong>scale</strong>. And eventually, you care about how AI fits into the organization itself.</p><p>That’s why the useful question isn’t <em>“Are we using AI?”</em></p><p>It’s:</p><blockquote><strong><em>How deeply is AI embedded in the way we work, build, review, govern, and ship?</em></strong></blockquote><p>There are five stages to that journey:</p><p><strong>Gated → Assisted → Parallel → Supervised autonomy → AI-native</strong></p><p>Each one has a shape, a bottleneck, an unlock, and its own guardrails. Let’s walk through them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tnt77zfKIr42Nn5pJzXlPg.png" /></figure><h3>Adoption is a curve, not a switch</h3><p>Here’s the trap: teams almost always think they’re further along than they are.</p><p>A team can use AI every single day and still be stuck at Stage 1. Another can run multiple AI workflows and still be stuck at Stage 2. A third can automate a ton and still not be AI-native — because the <em>governance</em> isn’t mature enough.</p><p>Your stage isn’t about how excited you are. It’s about how deeply AI is woven into the actual work.</p><p>And the honest way to find your stage is to answer a few practical questions:</p><ul><li>Should AI be limited to a few approved tools?</li><li>Should one engineer use one agent at a time?</li><li>Should one person orchestrate <em>many</em> agents?</li><li>Should AI write most of the code under supervision?</li><li>Or should AI be part of how the workflow is <em>designed</em>?</li></ul><p>Your answers place you on the curve. So let’s map it.</p><h3>Stage 0 — Gated</h3><p><strong>AI is allowed. But only under strict control.</strong></p><p>This is where most organizations start, and for good reason. The company wants to prevent data leakage, control cost, avoid unsafe usage, and keep approval visibility. It doesn’t yet trust the system enough to let everyone use everything.</p><p>So AI gets treated like a <em>managed capability</em>, not a default part of work. Access runs through approval workflows. Maybe only lighter or older models are sanctioned. Internal tools sit behind AI gateways and custom auth. Latency and cost-per-token are live concerns.</p><p><strong>The bottleneck:</strong> legacy security and approval overhead. Decisions get driven by compliance, not engineering speed — which is exactly why this stage feels slower than people expect.</p><p><strong>The unlock isn’t “use more AI.”</strong> It’s building a safe, low-risk <em>entry point</em> for real work: clear policies, role-based access, budget controls, approved model settings, and logging you can audit. Once people can use AI without breaking trust, the next stage opens up.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rGZVE6koDBdGjhH3bCP6kQ.png" /></figure><h3>Stage 1 — Assisted</h3><p><strong>One engineer. One agent. A fast pair programmer.</strong></p><p>This is the stage everyone recognizes on sight. The agent drafts code, explains it, refactors it, writes tests, knocks out the routine task between meetings. It speeds up the small things — but the human is firmly in charge. Every meaningful output gets reviewed before it merges.</p><p>The value is simple: <em>you move faster, but you still own the outcome.</em></p><p><strong>The bottleneck:</strong> trust and verification. The model is often “almost right” — and almost-right is expensive, because you spend real time reading, checking, and correcting. The help is obvious; the question is how much time you still burn verifying it.</p><p><strong>The unlock:</strong> a workflow that validates for you. Automated tests, linting, build checks, review support, fast feedback loops, safe local experimentation, a clean line between draft and final. Once you trust the <em>workflow</em>, you can start running more than one task at a time.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LYwr90l0W7zF8QLyB5b-lg.png" /></figure><h3>Stage 2 — Parallel</h3><p><strong>One engineer orchestrates many agents at once.</strong></p><p>This is the shift that changes the job. Instead of one agent on one task, you’re supervising five to ten agents — each on its own task or worktree, each producing its own stream of output. Auto mode may be on. AI checks its own work. Review becomes structured, happening at the end rather than after every line.</p><p>You stop being a writer and become a <strong>coordinator</strong>. The work moves from <em>“write everything yourself”</em> to <em>“break it into pieces, delegate, and verify.”</em> And the output multiplies.</p><p><strong>The bottleneck:</strong> review overhead. You’re no longer hand-writing steps — you’re checking many streams at once. Done well, that’s a massive multiplier. Done poorly, it’s mentally exhausting. The constraint is no longer code generation; it’s reviewing output, steering the model, and managing sessions.</p><p><strong>The unlock:</strong> trustworthy coordination. Clear work isolation, reliable review flows, automated quality checks, and monitoring of agent behavior. Once you can trust a parallel system, autonomy becomes possible.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*47AhvyKv5vfiReVZTh4Q1w.png" /></figure><h3>Stage 3 — Supervised autonomy</h3><p><strong>AI writes nearly all the code. Humans own oversight, quality, and direction.</strong></p><p>Now you’re less of a co-writer and more of a <em>manager of intelligent execution</em>. AI writes most or nearly all of the code. Subagents handle smaller tasks with work tree isolation. Routines and loops absorb the repetitive work. Agent trees get more sophisticated. And a new question becomes very real: <em>“Did you actually read the code?”</em></p><p>The system isn’t just helping one engineer write faster anymore. It’s helping the whole team scale delivery.</p><p><strong>The bottleneck:</strong> trust in the loop and the quality of the agent tree. Scale it carelessly and the tree gets too deep to babysit. This stage demands disciplined token management, structured agent design, and a clear line on what AI should — and shouldn’t — do.</p><p><strong>The unlock:</strong> stop thinking in individual AI tasks and start thinking in <em>systems</em>. Process-level automation. Intent-based workflows. Guardrails by category of work. Policy-based routing. Centralized observability. This is where you stop <em>enhancing</em> your systems with AI and start <em>designing</em> them around it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MzfSvuORu60W9HGHShDnYA.png" /></figure><h3>Stage 4 — AI-native</h3><p><strong>AI isn’t a tool people use. It’s how the organization runs.</strong></p><p>This is the mature end of the curve. Agents are triggered by intent — hundreds, even thousands of them. Tasks route automatically to the right model under the right policy. Automation is <em>designed</em>, not bolted on, and it spans repeated business and engineering processes alike.</p><p>AI has crossed the line from “helpful assistant” to “operating model.”</p><p><strong>The bottleneck:</strong> scale, governance, and model selection. Once AI is everywhere, the questions change entirely — How do we control cost? How do we pick the right model per task? How do we enforce policy consistently, measure quality across many agents, keep humans in the loop where it matters, and manage telemetry and compliance? The question is no longer <em>whether</em> AI is useful. It’s how to run it responsibly at scale.</p><p><strong>The unlock:</strong> a genuine platform. Policy-based access, model routing, observability, telemetry export, budget controls, governance packages, standardized workflows, reusable agent patterns.</p><p>Because AI-native never meant <em>“we use a lot of AI.”</em> It means <em>“our systems are built so AI can be used safely and repeatedly as part of how we operate.”</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*60x26wWOOixIlEg9R0w1gg.png" /></figure><h3>How the stages connect</h3><p>Line them up and the story is clean:</p><ul><li><strong>Gated</strong> — controlled access</li><li><strong>Assisted</strong> — individual productivity</li><li><strong>Parallel</strong> — orchestration</li><li><strong>Supervised autonomy</strong> — delegation at scale</li><li><strong>AI-native</strong> — operating-model transformation</li></ul><p>Each stage is blocked by a different thing — and naming that thing is the whole point.</p><h3>If you’re a leader</h3><p>This model reframes adoption as an <em>organizational</em> problem, not just a technical one. The next stage is almost always blocked by one of these: security and governance, review overhead, missing automation, low trust in output quality, poor workflow design, unclear ownership, or cost and control concerns.</p><p>So don’t just ask <em>“Are our teams using AI?”</em> Ask:</p><ul><li>What stage are we actually in?</li><li>What’s the bottleneck right now?</li><li>What unlocks the next stage?</li><li>What guardrails do we need <em>at this stage</em>?</li><li>What would break if we moved too fast?</li><li>What should stay manual even if AI got better?</li></ul><p>Those questions turn a vague ambition into a roadmap.</p><h3>If you’re a developer</h3><p>The model also explains something you’ve probably felt: why AI feels <em>magic</em> in one setting and <em>maddening</em> in another.</p><ul><li>In <strong>Assisted</strong> mode, it’s great for drafting and exploration.</li><li>In <strong>Parallel</strong> mode, it shines at delegating chunks of work.</li><li>In <strong>Supervised autonomy</strong>, it’s powerful — but demands sharper review habits.</li><li>In <strong>AI-native</strong> systems, it’s not a personal productivity toy anymore. It’s part of the platform.</li></ul><p>Which means your skill set has to evolve: from prompting and verification toward task decomposition, workflow design, tool orchestration, policy awareness, and cost-and-quality judgment.</p><p>The better your AI environment gets, the less <em>“just using AI”</em> matters — and the more <em>“designing how AI is used”</em> becomes the real skill.</p><h3>Final thought</h3><p>The five-stage model is valuable because it turns a fuzzy conversation into a concrete one. Instead of <em>“we should adopt AI,”</em> your team can say: <em>“here’s where we are, here’s what’s blocking us, here’s what the next stage needs.”</em></p><p>It’s also more honest. Not every team is ready for AI-native workflows. Not every team should leap straight to autonomous systems. Not every workflow benefits from the same depth of AI.</p><p>But almost any team can move forward once it sees the progression for what it is:</p><p><strong>Gated → Assisted → Parallel → Supervised autonomy → AI-native</strong></p><p>Not a single leap.</p><p>A maturity curve.</p><p>And the teams that understand the curve are the ones that will adopt AI safely, effectively, and at scale.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e5f80da50b09" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Agent Graph Engineering: From Prompt to Context, Skills, Loops, and Graphs]]></title>
            <link>https://medium.com/@balmikprajapati53/ai-agent-graph-engineering-from-prompt-to-context-skills-loops-and-graphs-77595f907570?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/77595f907570</guid>
            <category><![CDATA[langgraph]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Mon, 03 Aug 2026 09:34:40 GMT</pubDate>
            <atom:updated>2026-08-03T09:34:40.073Z</atom:updated>
            <content:encoded><![CDATA[<p>Most AI agent demos start with a simple promise:</p><p>Give the model a prompt.<br>Give it some context.<br>Give it a few tools.<br>Let it run in a loop.<br>Wait for the final answer.</p><p>For simple tasks, this works surprisingly well.</p><p>Ask an agent to summarize a document.<br>Ask it to search a knowledge base.<br>Ask it to call an API.<br>Ask it to generate a report.<br>Ask it to inspect an error log and suggest a fix.</p><p>In all these cases, a basic agent loop may be enough.</p><p>The agent thinks.<br>The agent chooses a tool.<br>The tool returns a result.<br>The agent observes the result.<br>The agent thinks again.<br>Eventually, it responds.</p><p>But production systems are different.</p><p>A production-grade AI agent is not just a prompt with tools.</p><p>It needs routing.<br>It needs state.<br>It needs memory.<br>It needs retries.<br>It needs error handling.<br>It needs human approval.<br>It needs observability.<br>It needs boundaries.<br>It needs predictable execution.</p><p>That is where the simple loop starts to feel too weak.</p><p>And that is where <strong>AI Agent Graph Engineering</strong> becomes important.</p><p>The evolution looks like this:</p><pre>Prompt -&gt; Context -&gt; Skills -&gt; Loop -&gt; Graph</pre><p>A prompt gives the agent direction.<br>Context gives the agent grounding.<br>Skills give the agent capabilities.<br>A loop gives the agent iteration.<br>A graph gives the agent architecture.</p><p>This article is about that shift.</p><p>We will start from the basic building blocks of an AI agent and then understand why graph-based agent design is becoming a better way to build reliable, auditable, and production-ready AI workflows.</p><h3>Introduction: The agent loop is not enough anymore</h3><p>The agent loop is one of the most powerful ideas in AI application development.</p><p>At a high level, it looks like this:</p><pre>Think -&gt; Act -&gt; Observe -&gt; Think Again -&gt; Continue or Finish</pre><p>The model receives a task, reasons about what to do, chooses a tool, observes the tool result, and continues until it has enough information to answer.</p><p>This pattern is useful because it gives the agent flexibility.</p><p>Instead of hardcoding every step, we allow the model to decide what to do next.</p><p>That is powerful.</p><p>But it is also risky.</p><p>A loop hides a lot of behavior inside one repeated cycle. When the task is simple, that is fine. But when the workflow becomes larger, the loop can become difficult to understand, debug, monitor, and control.</p><p>Imagine an AI production incident assistant.</p><p>It receives an alert from monitoring.</p><p>It needs to check service metadata.<br>It needs to read logs.<br>It needs to query metrics.<br>It needs to check recent deployments.<br>It needs to classify severity.<br>It needs to decide whether human approval is required.<br>It needs to suggest a remediation plan.</p><p>If all of this happens inside one open-ended loop, we may not clearly know:</p><p>Which step is currently running?<br>Why did the agent choose a specific tool?<br>Can this step be retried safely?<br>Where should human approval happen?<br>What happens if log retrieval fails?<br>What happens if metrics are unavailable?<br>Can we resume from the failure point?<br>Can we audit the decision later?</p><p>These questions matter in real systems.</p><p>That is the core limitation of the loop.</p><p>The loop gives the agent freedom.</p><p>The graph gives the system structure.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g20JjHxc_jUCrBCejJVqaA.png" /></figure><h3>Prompt: The starting point</h3><p>Every agent starts with a prompt.</p><p>The prompt defines what the agent is supposed to do.</p><p>For example:</p><pre>You are an AI incident triage assistant.<br>Analyze production alerts, gather relevant context, identify probable root cause,<br>and suggest safe remediation steps.</pre><p>This prompt gives the agent a role.</p><p>It tells the agent the desired behavior.</p><p>It may also include rules:</p><pre>Do not restart a production service without human approval.<br>Always check recent deployments before suggesting rollback.<br>If severity is critical, escalate to the on-call engineer.</pre><p>This is where many AI applications begin.</p><p>And for small use cases, a strong prompt can take you far.</p><p>But a prompt is not architecture.</p><p>A prompt cannot reliably define every transition in a complex workflow.<br>A prompt cannot guarantee that the agent will always call tools in the right order.<br>A prompt cannot replace permissions, validation, observability, or recovery logic.<br>A prompt cannot make a long-running workflow durable by itself.</p><p>A prompt is direction.</p><p>It is not control.</p><p>That distinction is important.</p><p>When developers first start building agents, they often try to solve everything by improving the prompt.</p><p>The prompt becomes longer.<br>More rules are added.<br>More examples are added.<br>More constraints are added.<br>More formatting instructions are added.</p><p>Eventually, the prompt becomes a hidden workflow engine written in natural language.</p><p>That is fragile.</p><p>A good agent design should not put all responsibility on the prompt.</p><p>The prompt should describe the agent’s role and behavior, but the system architecture should control execution.</p><p>In other words:</p><blockquote><em>The prompt should guide the agent. It should not carry the entire system design.</em></blockquote><h3>Context: The agent’s working memory</h3><p>After prompt comes context.</p><p>Context is what the agent knows at the time of execution.</p><p>This can include:</p><p>Conversation history<br>User input<br>Retrieved documents<br>API responses<br>Database records<br>Previous tool results<br>System state<br>Session memory<br>Business rules<br>Runtime environment details</p><p>For example, if we are building an AI incident triage agent, the context might include:</p><pre>Alert name: High error rate<br>Service: payment-service<br>Environment: production<br>Current error rate: 12%<br>Recent deployment: payment-service v2.8.1 deployed 15 minutes ago<br>Recent log pattern: Database connection timeout<br>SLO impact: Checkout failures increased</pre><p>This context makes the agent useful.</p><p>Without context, the model is just guessing.</p><p>With context, the model can reason about the actual situation.</p><p>But context also creates a new problem.</p><p>As the task grows, the context can become messy.</p><p>The agent may collect logs, metrics, tickets, deployment history, code snippets, documentation, and user instructions all in one large context window.</p><p>If we are not careful, the agent may mix old information with new information.<br>It may over-focus on irrelevant context.<br>It may forget important constraints.<br>It may treat untrusted data as trusted.<br>It may make decisions based on incomplete observations.</p><p>This is why context engineering matters.</p><p>A production agent should not simply keep adding everything into the prompt.</p><p>It needs structured context.</p><p>For example:</p><pre>{<br>  &quot;alert&quot;: {<br>    &quot;name&quot;: &quot;High error rate&quot;,<br>    &quot;service&quot;: &quot;payment-service&quot;,<br>    &quot;severity&quot;: &quot;critical&quot;<br>  },<br>  &quot;deployment&quot;: {<br>    &quot;version&quot;: &quot;2.8.1&quot;,<br>    &quot;deployedAt&quot;: &quot;15 minutes ago&quot;,<br>    &quot;owner&quot;: &quot;payments-team&quot;<br>  },<br>  &quot;metrics&quot;: {<br>    &quot;errorRate&quot;: &quot;12%&quot;,<br>    &quot;latencyP95&quot;: &quot;1800ms&quot;<br>  },<br>  &quot;logs&quot;: {<br>    &quot;topError&quot;: &quot;Database connection timeout&quot;<br>  },<br>  &quot;decisionState&quot;: {<br>    &quot;requiresHumanApproval&quot;: true,<br>    &quot;canAutoRemediate&quot;: false<br>  }<br>}</pre><p>This kind of structure is easier to inspect, update, validate, and pass between workflow steps.</p><p>That is one of the first signs that we are moving from a simple loop toward a graph.</p><p>In a graph-based agent system, context becomes state.</p><p>Each node reads state, updates state, and passes it to the next node.</p><p>That is much cleaner than letting one open-ended loop carry everything implicitly.</p><h3>Skills: Tools, APIs, functions, and MCP</h3><p>A prompt tells the agent what to do.</p><p>Context tells the agent what it knows.</p><p>Skills tell the agent what it can do.</p><p>In agent systems, skills usually mean external capabilities exposed to the model.</p><p>These can include:</p><p>Search tools<br>Database queries<br>REST APIs<br>Internal services<br>Code execution<br>File readers<br>Ticketing systems<br>Monitoring tools<br>Log platforms<br>Deployment systems<br>Notification services<br>MCP servers<br>Custom business functions</p><p>For example, an incident triage agent may have skills like:</p><pre>getServiceMetadata(serviceName)<br>queryLogs(serviceName, timeRange)<br>queryMetrics(serviceName, metricName)<br>getRecentDeployments(serviceName)<br>createIncidentTicket(summary, severity)<br>notifyOnCallEngineer(teamName)<br>generateRemediationPlan(context)</pre><p>Skills are what make agents practical.</p><p>Without skills, the agent can only produce text.</p><p>With skills, the agent can interact with real systems.</p><p>But tool access also introduces risk.</p><p>Should every agent be allowed to call every tool?<br>Can the agent restart a service?<br>Can it create a refund?<br>Can it send a customer email?<br>Can it update production configuration?<br>Can it access sensitive logs?<br>Can it call tools in any order?</p><p>This is where many agent demos become unrealistic.</p><p>In real systems, tool usage needs boundaries.</p><p>Some tools are read-only.<br>Some tools are write operations.<br>Some tools require approval.<br>Some tools are safe to retry.<br>Some tools are dangerous if repeated.<br>Some tools should only be available after a specific workflow step.</p><p>For example, this is safe:</p><pre>queryMetrics(payment-service, error_rate)</pre><p>This may require approval:</p><pre>rollbackDeployment(payment-service, previous_version)</pre><p>This should be heavily controlled:</p><pre>restartProductionDatabase()</pre><p>A loop-based agent may decide when to use tools dynamically, but a graph-based agent can make tool access more explicit.</p><p>For example:</p><pre>Log Retriever Node -&gt; can only call log tools<br>Metrics Checker Node -&gt; can only call metrics tools<br>Deployment Analyzer Node -&gt; can only call deployment tools<br>Human Approval Node -&gt; required before remediation tools<br>Remediation Node -&gt; can only run after approval</pre><p>This is the difference between “the agent can call tools” and “the system controls when tools are available.”</p><p>That difference matters in production.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*quYMwkHM86Tnz8ZaZ8UppA.png" /></figure><h3>Loop: How agents think-act-observe</h3><p>The agent loop is the classic execution pattern.</p><p>It usually works like this:</p><pre>1. Receive user goal<br>2. Think about next action<br>3. Choose a tool<br>4. Execute the tool<br>5. Observe the result<br>6. Update reasoning<br>7. Repeat until final answer</pre><p>In pseudocode, it may look like this:</p><pre>while not done:<br>    thought = model.reason(prompt, context, tool_results)<br>    action = model.choose_tool(thought)</pre><pre>    if action.type == &quot;tool_call&quot;:<br>        result = execute_tool(action.tool_name, action.arguments)<br>        tool_results.append(result)</pre><pre>    if action.type == &quot;final_answer&quot;:<br>        done = True<br>        return action.response</pre><p>This is simple and elegant.</p><p>It works well when the task is exploratory.</p><p>For example:</p><pre>Research this topic and summarize it.<br>Find the best API endpoint for this use case.<br>Debug this error message.<br>Search documentation and explain the answer.<br>Inspect these logs and tell me what might be wrong.</pre><p>In these cases, the agent does not always know the exact path upfront.</p><p>The loop allows it to explore.</p><p>That is why loops are useful.</p><p>They provide flexibility.</p><p>But flexibility can become a weakness when the workflow requires structure.</p><p>Let’s say we ask an agent:</p><pre>Investigate this production alert and recommend remediation.</pre><p>Inside a loop, the agent may decide to:</p><p>Check logs first.<br>Or check metrics first.<br>Or check deployments first.<br>Or jump directly to a recommendation.<br>Or call the same tool multiple times.<br>Or miss a required approval step.</p><p>Sometimes that is acceptable.</p><p>Sometimes it is not.</p><p>For production workflows, we often need a more predictable path.</p><p>That is when a graph becomes useful.</p><h3>The problem with loops</h3><p>The problem with loops is not that they are bad.</p><p>The problem is that they are too general.</p><p>A loop says:</p><pre>Keep reasoning and acting until the task is done.</pre><p>That is powerful, but it leaves many important questions unanswered.</p><h3>1. Loops can be hard to debug</h3><p>If an agent makes a bad decision, we need to understand why.</p><p>But in a loop, the reasoning path may be long and dynamic.</p><p>The agent may call several tools, update context multiple times, and change direction based on intermediate results.</p><p>Without strong tracing, it becomes difficult to answer:</p><pre>Which step failed?<br>Which tool result caused the wrong conclusion?<br>Why did the agent choose this action?<br>Was this action allowed?<br>Could the workflow be resumed?</pre><p>A graph gives each step a name.</p><p>That makes debugging easier.</p><p>Instead of saying “the agent failed somewhere in the loop,” we can say:</p><pre>The workflow failed at the Metrics Checker node.</pre><p>That is much more useful.</p><h3>2. Loops can be hard to control</h3><p>In a loop, the model often decides the next step.</p><p>But some systems need strict control.</p><p>For example:</p><pre>Do not suggest rollback before checking recent deployments.<br>Do not notify executives before severity classification.<br>Do not execute remediation before human approval.<br>Do not access customer data unless the incident requires it.</pre><p>These rules can be written in the prompt, but prompt rules are not the same as execution constraints.</p><p>A graph can enforce the order.</p><pre>Alert -&gt; Classify Severity -&gt; Gather Evidence -&gt; Human Approval -&gt; Remediation</pre><p>The model may still reason inside each node, but the system controls the path.</p><h3>3. Loops can repeat unnecessary work</h3><p>Agents sometimes call the same tool repeatedly.</p><p>For example:</p><pre>queryLogs(payment-service)<br>queryLogs(payment-service)<br>queryLogs(payment-service)</pre><p>Sometimes this happens because the model is uncertain. Sometimes because the context was not structured well. Sometimes because the tool result was not clear.</p><p>In a graph, repeated work can be controlled.</p><p>A node can run once.<br>A result can be cached.<br>A retry policy can be defined.<br>A failure path can be handled explicitly.</p><h3>4. Loops are weak for human-in-the-loop workflows</h3><p>Human approval is common in real systems.</p><p>For example:</p><pre>Approve refund<br>Approve deployment rollback<br>Approve customer notification<br>Approve production remediation<br>Approve access to sensitive data</pre><p>In a simple loop, human approval often becomes a tool call or a prompt instruction.</p><p>In a graph, human approval can be a first-class node.</p><pre>Root Cause Analysis -&gt; Human Approval -&gt; Remediation Plan</pre><p>The workflow can pause, wait, resume, or reject.</p><p>That is much closer to how real enterprise workflows behave.</p><h3>5. Loops are harder to audit</h3><p>For production AI systems, auditability matters.</p><p>We may need to know:</p><p>What data was used?<br>Which tools were called?<br>Who approved the action?<br>What state changed?<br>What recommendation was generated?<br>What was the final outcome?</p><p>A graph gives us a natural audit trail.</p><p>Each node becomes an auditable step.</p><p>Each edge becomes a transition.</p><p>Each state update becomes part of the execution record.</p><p>That is why graph-based agents are not just a developer convenience.</p><p>They are an architectural pattern.</p><h3>Graph: Turning agent behavior into architecture</h3><p>A graph-based agent design models the workflow explicitly.</p><p>Instead of one open-ended loop, we define:</p><p>Nodes<br>Edges<br>State<br>Transitions<br>Conditions<br>Retry paths<br>Failure paths<br>Human approval points<br>Terminal states</p><p>A simple graph might look like this:</p><pre>Start<br>  |<br>  v<br>Understand Request<br>  |<br>  v<br>Retrieve Context<br>  |<br>  v<br>Choose Action<br>  |<br>  +----&gt; Call Tool<br>  |        |<br>  |        v<br>  |     Update State<br>  |        |<br>  |        v<br>  +----&gt; Decide Next Step<br>           |<br>           v<br>        Final Answer</pre><p>A more realistic incident agent graph might look like this:</p><pre>Alert Received<br>      |<br>      v<br>Classify Severity<br>      |<br>      v<br>Fetch Service Metadata<br>      |<br>      v<br>Query Logs<br>      |<br>      v<br>Query Metrics<br>      |<br>      v<br>Check Recent Deployments<br>      |<br>      v<br>Analyze Root Cause<br>      |<br>      +-------------------+<br>      |                   |<br>      v                   v<br>Human Approval       Low-Risk Recommendation<br>      |                   |<br>      v                   v<br>Remediation Plan     Final Response<br>      |<br>      v<br>Final Response</pre><p>This graph gives structure to the agent.</p><p>Each node has a responsibility.</p><p>For example:</p><pre>Classify Severity Node:<br>Input: alert details<br>Output: severity level</pre><pre>Query Logs Node:<br>Input: service name and time range<br>Output: relevant log patterns</pre><pre>Query Metrics Node:<br>Input: service name and metrics list<br>Output: latency, error rate, throughput</pre><pre>Analyze Root Cause Node:<br>Input: logs, metrics, deployments, service metadata<br>Output: probable cause and confidence</pre><pre>Human Approval Node:<br>Input: recommended action<br>Output: approved or rejected</pre><pre>Final Response Node:<br>Input: complete workflow state<br>Output: user-facing answer</pre><p>Now the system is easier to reason about.</p><p>We are no longer depending on one loop to decide everything.</p><p>The graph defines the architecture.</p><p>The model can still reason, but within controlled boundaries.</p><p>That is the key idea of AI Agent Graph Engineering.</p><blockquote><em>Do not remove the model’s intelligence. Structure it.</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0SXWMaz1yiUwLZhU3F_WEw.png" /></figure><h3>Loop vs Graph</h3><p>The best way to understand graph engineering is to compare it directly with the loop pattern.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZzLXWqk1bpoQvIKQPmVlYQ.png" /></figure><p>This does not mean graphs always replace loops.</p><p>A graph can contain loops.</p><p>For example, a node may retry a tool call.<br>A reviewer node may send the workflow back for more context.<br>A planner node may revisit the retrieval step.<br>A remediation workflow may loop until validation passes.</p><p>The difference is that the loop is now controlled inside a graph.</p><p>Instead of one large open-ended loop, we create smaller, intentional loops where they make sense.</p><p>That is an important design shift.</p><p>The question is not:</p><pre>Loop or graph?</pre><p>The better question is:</p><pre>Where should the loop live inside the graph?</pre><p>A production agent often uses both.</p><p>The graph provides the structure.</p><p>Loops provide local iteration.</p><p>That combination is powerful.</p><h3>A practical example: AI incident triage agent</h3><p>Let’s make this concrete.</p><p>Imagine we are building an AI incident triage agent for a backend platform.</p><p>A production alert arrives:</p><pre>Alert: High checkout failure rate<br>Service: payment-service<br>Environment: production<br>Error rate: 12%<br>Time window: last 15 minutes</pre><p>The goal of the agent is to help the on-call engineer understand what happened.</p><p>A simple loop-based approach might look like this:</p><pre>Agent receives alert.<br>Agent decides to check logs.<br>Agent decides to check metrics.<br>Agent decides to check deployments.<br>Agent summarizes possible root cause.<br>Agent suggests remediation.</pre><p>This works for a demo.</p><p>But for production, we want something more structured.</p><p>We can design a graph.</p><pre>Alert Received<br>  |<br>  v<br>Severity Classifier<br>  |<br>  v<br>Service Context Retriever<br>  |<br>  v<br>Evidence Collector<br>  |<br>  +--&gt; Logs Retriever<br>  |<br>  +--&gt; Metrics Checker<br>  |<br>  +--&gt; Deployment Checker<br>  |<br>  v<br>Root Cause Analyzer<br>  |<br>  v<br>Risk Evaluator<br>  |<br>  +--&gt; Human Approval Required<br>  |<br>  +--&gt; Safe Recommendation<br>  |<br>  v<br>Final Incident Summary</pre><p>Each node has a clear responsibility.</p><h3>Node 1: Alert Received</h3><p>This node receives the original alert.</p><pre>{<br>  &quot;alertName&quot;: &quot;High checkout failure rate&quot;,<br>  &quot;service&quot;: &quot;payment-service&quot;,<br>  &quot;environment&quot;: &quot;production&quot;,<br>  &quot;errorRate&quot;: &quot;12%&quot;,<br>  &quot;timeWindow&quot;: &quot;15 minutes&quot;<br>}</pre><p>It validates that the required fields are present.</p><p>If important data is missing, the workflow can stop early or ask for more input.</p><h3>Node 2: Severity Classifier</h3><p>This node decides the incident severity.</p><p>For example:</p><pre>{<br>  &quot;severity&quot;: &quot;critical&quot;,<br>  &quot;reason&quot;: &quot;Checkout failures affect payment completion in production&quot;<br>}</pre><p>This step is important because severity affects the rest of the workflow.</p><p>A low-severity alert may only need a summary.</p><p>A critical alert may require on-call escalation.</p><h3>Node 3: Service Context Retriever</h3><p>This node fetches service metadata.</p><p>For example:</p><pre>{<br>  &quot;service&quot;: &quot;payment-service&quot;,<br>  &quot;owner&quot;: &quot;payments-team&quot;,<br>  &quot;dependencies&quot;: [&quot;order-service&quot;, &quot;wallet-service&quot;, &quot;postgres-db&quot;],<br>  &quot;runbook&quot;: &quot;payment-service-runbook.md&quot;<br>}</pre><p>Now the agent knows who owns the service and what dependencies matter.</p><h3>Node 4: Evidence Collector</h3><p>This part can branch into multiple nodes.</p><p>One node checks logs.</p><pre>{<br>  &quot;topError&quot;: &quot;Database connection timeout&quot;,<br>  &quot;errorCount&quot;: 1482<br>}</pre><p>Another node checks metrics.</p><pre>{<br>  &quot;latencyP95&quot;: &quot;1800ms&quot;,<br>  &quot;dbConnectionPoolUsage&quot;: &quot;98%&quot;,<br>  &quot;errorRate&quot;: &quot;12%&quot;<br>}</pre><p>Another node checks deployments.</p><pre>{<br>  &quot;recentDeployment&quot;: true,<br>  &quot;version&quot;: &quot;2.8.1&quot;,<br>  &quot;deployedAt&quot;: &quot;14 minutes ago&quot;<br>}</pre><p>Now the graph has gathered structured evidence.</p><h3>Node 5: Root Cause Analyzer</h3><p>This node receives all evidence and creates a hypothesis.</p><pre>{<br>  &quot;probableCause&quot;: &quot;Recent deployment may have increased database connection usage&quot;,<br>  &quot;confidence&quot;: &quot;medium&quot;,<br>  &quot;supportingEvidence&quot;: [<br>    &quot;Deployment happened 14 minutes ago&quot;,<br>    &quot;Database connection pool usage is 98%&quot;,<br>    &quot;Logs show database connection timeouts&quot;,<br>    &quot;Checkout failure rate increased after deployment&quot;<br>  ]<br>}</pre><p>This node does not blindly act.</p><p>It analyzes.</p><h3>Node 6: Risk Evaluator</h3><p>This node decides whether human approval is required.</p><p>For example:</p><pre>{<br>  &quot;requiresHumanApproval&quot;: true,<br>  &quot;reason&quot;: &quot;Suggested action may affect production payment traffic&quot;<br>}</pre><p>If the recommendation is only informational, the workflow may proceed to final response.</p><p>If the recommendation involves rollback, restart, or configuration change, human approval is required.</p><h3>Node 7: Human Approval</h3><p>This node pauses the workflow.</p><pre>Recommended action: Roll back payment-service from v2.8.1 to v2.8.0.<br>Approval required from payments-team on-call engineer.</pre><p>The workflow does not continue until approval is received.</p><p>This is much safer than allowing the model to perform production actions directly.</p><h3>Node 8: Final Incident Summary</h3><p>The final node produces a clear summary:</p><pre>Incident Summary:<br>The payment-service is experiencing a high checkout failure rate.</pre><pre>Probable Cause:<br>Recent deployment v2.8.1 may have increased database connection usage,<br>leading to connection pool exhaustion and database timeout errors.</pre><pre>Evidence:<br>- Error rate increased to 12%<br>- Database pool usage reached 98%<br>- Logs show database connection timeouts<br>- Deployment happened 14 minutes before alert</pre><pre>Recommended Action:<br>Review deployment v2.8.1 and consider rollback after human approval.</pre><p>This is not just an AI response.</p><p>It is the output of a structured workflow.</p><p>That is the value of graph engineering.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*M3UqUQmM-G5ilavifHDfVQ.png" /></figure><h3>Graph engineering principles</h3><p>Graph-based agents need good design.</p><p>A messy graph can become just as confusing as a messy loop.</p><p>Here are practical principles for designing agent graphs.</p><h3>1. Make each node responsible for one thing</h3><p>A node should have a clear purpose.</p><p>Good nodes:</p><pre>Classify Severity<br>Retrieve Logs<br>Check Metrics<br>Validate Request<br>Generate Summary<br>Ask Human Approval</pre><p>Bad nodes:</p><pre>Do Everything<br>Analyze And Fix<br>Handle Incident<br>Process Request</pre><p>If a node does too much, it becomes another hidden loop.</p><p>Keep nodes focused.</p><h3>2. Keep state explicit</h3><p>State should be structured and inspectable.</p><p>Instead of passing one huge text blob, define state clearly.</p><p>Example:</p><pre>{<br>  &quot;alert&quot;: {},<br>  &quot;serviceMetadata&quot;: {},<br>  &quot;logs&quot;: {},<br>  &quot;metrics&quot;: {},<br>  &quot;deployments&quot;: {},<br>  &quot;rootCause&quot;: {},<br>  &quot;approval&quot;: {},<br>  &quot;finalResponse&quot;: {}<br>}</pre><p>This makes the workflow easier to debug.</p><h3>3. Separate reasoning from action</h3><p>Reasoning and action should not always live in the same place.</p><p>For example:</p><pre>Root Cause Analyzer -&gt; reasons about the issue<br>Human Approval -&gt; approves or rejects action<br>Remediation Executor -&gt; performs the action</pre><p>This separation is important.</p><p>The agent may suggest a rollback, but the system should decide whether rollback is allowed.</p><h3>4. Add guardrails at transitions</h3><p>Edges should not be random.</p><p>Each transition should have a condition.</p><p>For example:</p><pre>If severity = critical -&gt; notify on-call<br>If confidence &lt; 0.6 -&gt; collect more evidence<br>If action = production change -&gt; require approval<br>If logs unavailable -&gt; continue with partial evidence</pre><p>This makes the graph safer.</p><h3>5. Design for failure</h3><p>Every important node should have a failure path.</p><p>What if logs are unavailable?<br>What if metrics API times out?<br>What if the deployment service is down?<br>What if human approval is rejected?<br>What if the model output is invalid?</p><p>A production graph should not assume the happy path.</p><p>It should handle failure explicitly.</p><h3>6. Use loops intentionally</h3><p>Loops are still useful.</p><p>But they should be controlled.</p><p>Examples:</p><pre>Retry log query up to 3 times<br>Ask for missing input until required fields are present<br>Re-run analysis after new evidence is collected<br>Validate generated response until schema is correct</pre><p>A graph does not eliminate loops.</p><p>It makes loops intentional.</p><h3>7. Add observability from the beginning</h3><p>Every node should be traceable.</p><p>For each execution, we should know:</p><p>Node name<br>Input state<br>Output state<br>Tool calls<br>Errors<br>Latency<br>Retries<br>Approval decisions<br>Final result</p><p>This is essential for production AI systems.</p><p>If we cannot observe the agent, we cannot trust it.</p><h3>8. Keep humans in control for high-risk actions</h3><p>AI agents should not automatically perform sensitive actions without approval.</p><p>Examples of high-risk actions:</p><p>Production rollback<br>Payment refund<br>Account suspension<br>Customer notification<br>Database migration<br>Security policy update<br>Infrastructure scaling<br>Access permission change</p><p>For these actions, the graph should include a human approval node.</p><p>This is not a weakness.</p><p>It is responsible design.</p><h3>When to use loop and when to use graph</h3><p>Loops and graphs are both useful.</p><p>The goal is not to say one is always better.</p><p>The goal is to choose the right pattern for the job.</p><p>Use a loop when:</p><p>The task is simple.<br>The task is exploratory.<br>The risk is low.<br>The workflow does not need strict ordering.<br>The agent only reads information.<br>The task can be completed in a few tool calls.<br>Failure does not create serious business impact.</p><p>Examples:</p><pre>Summarize a document<br>Search documentation<br>Generate a draft email<br>Answer a support question<br>Analyze a small log snippet<br>Create a short report</pre><p>Use a graph when:</p><p>The task has multiple phases.<br>The workflow needs clear control.<br>The system needs auditability.<br>There are different paths based on conditions.<br>Human approval may be required.<br>Some tools are sensitive.<br>The workflow may run for a long time.<br>The agent needs to resume after failure.<br>The output affects production, money, security, or customers.</p><p>Examples:</p><pre>Incident triage agent<br>Payment dispute assistant<br>AI release risk reviewer<br>Customer support escalation agent<br>Fraud investigation workflow<br>Healthcare claim review workflow<br>Production remediation assistant<br>Enterprise onboarding assistant</pre><p>A simple rule:</p><blockquote><em>Use loops for exploration. Use graphs for workflows.</em></blockquote><p>Another useful rule:</p><blockquote><em>If you need to draw the process for a human reviewer, you probably need a graph.</em></blockquote><h3>Final thoughts</h3><p>AI agent development often begins with a prompt.</p><p>Then we add context.</p><p>Then we add tools.</p><p>Then we put everything inside a loop.</p><p>That is a natural learning path.</p><pre>Prompt -&gt; Context -&gt; Skills -&gt; Loop</pre><p>But production agent systems need one more step.</p><pre>Prompt -&gt; Context -&gt; Skills -&gt; Loop -&gt; Graph</pre><p>The graph is where agent development becomes agent engineering.</p><p>It turns hidden behavior into visible architecture.</p><p>It makes workflows easier to debug.<br>It makes tool usage easier to control.<br>It makes human approval easier to integrate.<br>It makes state easier to inspect.<br>It makes failures easier to handle.<br>It makes production systems easier to trust.</p><p>The loop gives the agent freedom.</p><p>The graph gives the system responsibility.</p><p>And that is the balance we need.</p><p>Because the future of AI agents is not just about making models more autonomous.</p><p>It is about making agent systems more reliable.</p><p>A good production agent is not simply one that can think and act.</p><p>A good production agent is one whose thinking and actions are structured, observable, recoverable, and safe.</p><p>That is the real value of AI Agent Graph Engineering.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=77595f907570" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Idempotency Keys in Payment APIs: The Small Header That Prevents Double Charges]]></title>
            <link>https://medium.com/@balmikprajapati53/idempotency-keys-in-payment-apis-the-small-header-that-prevents-double-charges-b76c1ceb0066?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/b76c1ceb0066</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[backend-development]]></category>
            <category><![CDATA[payment-api]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[spring-boot]]></category>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Tue, 28 Jul 2026 18:09:55 GMT</pubDate>
            <atom:updated>2026-07-28T18:10:50.629Z</atom:updated>
            <content:encoded><![CDATA[<h3>Introduction: Why retries are dangerous in payment systems</h3><p>In most backend systems, retries are a good thing.</p><p>If a network call fails, retry it.<br>If a service times out, retry it.<br>If the mobile app does not receive a response, retry it.<br>If an API gateway gets a temporary error, retry it.</p><p>Retries make distributed systems more reliable.</p><p>But in payment systems, retries can become dangerous.</p><p>Imagine a customer clicking the <strong>Pay Now</strong> button. The backend receives the request, creates a payment, and maybe even starts processing it with a payment provider. But before the response reaches the frontend, the user’s network drops.</p><p>From the frontend’s point of view, the payment failed.</p><p>So the app retries.</p><p>From the backend point of view, this may now look like a brand-new payment request.</p><p>And if the backend is not careful, the same customer may be charged twice.</p><p>That is why payment APIs need more than normal request handling. They need protection against duplicate side effects.</p><p>This is where an <strong>idempotency key</strong> becomes important.</p><p>An idempotency key is usually just a small request header, but in payment systems, it plays a very important role:</p><blockquote><em>It tells the backend, “This request may be retried, but it still represents the same business operation.”</em></blockquote><p>That small idea can prevent duplicate payments, duplicate orders, duplicate notifications, and a lot of production pain.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FyXu-uqE9dGpzjrMqW3pzg.png" /></figure><h3>The double-payment problem</h3><p>Let’s start with a simple payment flow.</p><p>A customer places an order and initiates payment.</p><pre>POST /api/payments/initiate<br>Content-Type: application/json</pre><pre>{<br>  &quot;orderId&quot;: &quot;ORD-1001&quot;,<br>  &quot;amount&quot;: 2499.00,<br>  &quot;currency&quot;: &quot;INR&quot;<br>}</pre><p>Now imagine the first request succeeds on the server, but the client never receives the response.</p><p>Without idempotency, the retry may create another payment.</p><pre>Request 1 -&gt; creates payment PAY-1001<br>Request 2 -&gt; creates payment PAY-1002</pre><p>From a database point of view, there are now two payment records.</p><p>From a customer point of view, this may become a double charge.</p><p>From an engineering point of view, this is a serious reliability bug.</p><p>The dangerous part is that no one intentionally created the duplicate. It happened because of a normal distributed system behavior: retry after failure.</p><p>This can happen due to many reasons:</p><p>A user double-clicks the Pay button.</p><p>A mobile network disconnects after the server processes the payment.</p><p>A frontend retry mechanism sends the same request again.</p><p>An API gateway retries after a timeout.</p><p>A webhook provider sends the same callback multiple times.</p><p>A message consumer processes the same event more than once.</p><p>In payment systems, duplicate requests are not edge cases. They are expected.</p><p>So the backend must be designed with this assumption:</p><blockquote><em>The same request can arrive more than once.</em></blockquote><p>With idempotency, the flow changes.</p><pre>Request 1 -&gt; creates payment PAY-1001<br>Request 2 -&gt; returns existing payment PAY-1001</pre><p>The second request does not create a new payment. It returns the original result.</p><p>That is the core idea.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6AH389qL7gwWmQ8wn8wwVQ.jpeg" /></figure><h3>What is an idempotency key?</h3><p>An idempotency key is a unique value sent by the client with a request so the server can detect duplicate attempts of the same operation.</p><p>Usually, the client sends it as an HTTP header.</p><pre>POST /api/payments/initiate<br>Idempotency-Key: 8d7f0c2a-91b1-4e2a-9d11-7a6c8f9e1234<br>Content-Type: application/json</pre><pre>{<br>  &quot;orderId&quot;: &quot;ORD-1001&quot;,<br>  &quot;amount&quot;: 2499.00,<br>  &quot;currency&quot;: &quot;INR&quot;<br>}</pre><p>The key should be unique for one logical operation.</p><p>For example, if the user is trying to pay for ORD-1001, the frontend or client application generates one idempotency key for that payment attempt.</p><p>If the request times out, the client retries using the same key.</p><pre>POST /api/payments/initiate<br>Idempotency-Key: 8d7f0c2a-91b1-4e2a-9d11-7a6c8f9e1234</pre><p>The backend checks whether this key was already processed.</p><p>If it is a new key, the backend creates the payment and stores the result.</p><p>If the same key comes again, the backend returns the previous result instead of creating another payment.</p><p>In simple words:</p><blockquote><em>Same idempotency key. Same request. Same result. No duplicate side effect.</em></blockquote><p>This is especially useful for APIs that perform important business operations, such as:</p><p>Payment creation</p><p>Order placement</p><p>Refund initiation</p><p>Wallet transfer</p><p>Subscription purchase</p><p>Invoice generation</p><p>Webhook processing</p><p>Any operation where duplicate execution can create business damage is a good candidate for idempotency protection.</p><h3>Idempotency vs HTTP idempotent methods</h3><p>Before going deeper, it is important to separate two ideas:</p><ol><li>HTTP idempotent methods</li><li>Application-level idempotency keys</li></ol><p>In HTTP, some methods are naturally idempotent.</p><p>For example, GET is idempotent because calling it multiple times should not change the resource.</p><pre>GET /api/orders/ORD-1001</pre><p>Calling this once or ten times should have the same effect on the server state.</p><p>PUT is also idempotent when used correctly.</p><pre>PUT /api/customers/123<br>Content-Type: application/json</pre><pre>{<br>  &quot;name&quot;: &quot;Balmik&quot;,<br>  &quot;email&quot;: &quot;balmik@example.com&quot;<br>}</pre><p>If the same update is sent multiple times, the final state remains the same.</p><p>DELETE is also considered idempotent because deleting the same resource multiple times should leave the system in the same final state. The response may differ, but the final state is unchanged.</p><p>But POST is different.</p><p>POST is not idempotent by default.</p><pre>POST /api/payments/initiate</pre><p>Every POST request may create a new resource or trigger a new business action.</p><p>That is why payment initiation APIs are risky. They are usually POST APIs because they create a payment attempt or start a payment workflow.</p><p>So how do we make a POST payment API safer?</p><p>We add application-level idempotency using an idempotency key.</p><p>This does not mean the HTTP POST method itself becomes globally idempotent. It means this specific business operation becomes idempotent because the backend uses the key to detect duplicates.</p><p>That distinction is important in interviews.</p><p>A good answer is:</p><blockquote><em>POST is not idempotent by default, but we can design a POST endpoint to behave idempotently by using an idempotency key.</em></blockquote><h3>How idempotency works in payment APIs</h3><p>Let’s walk through a practical payment initiation flow.</p><p>The client sends a payment request with an idempotency key.</p><pre>POST /api/payments/initiate<br>Idempotency-Key: 1f7b9c2e-0d8a-4a7e-91d5-33e5c7d98f10<br>Content-Type: application/json</pre><pre>{<br>  &quot;orderId&quot;: &quot;ORD-1001&quot;,<br>  &quot;amount&quot;: 2499.00,<br>  &quot;currency&quot;: &quot;INR&quot;<br>}</pre><p>The backend follows this logic:</p><pre>1. Read Idempotency-Key from request header<br>2. Validate that the key is present<br>3. Generate a hash/fingerprint of the request payload<br>4. Check if the key already exists<br>5. If key does not exist:<br>      - create payment<br>      - save idempotency record<br>      - return payment response<br>6. If key exists with same request hash:<br>      - return original response<br>7. If key exists with different request hash:<br>      - reject the request</pre><p>The request hash is important.</p><p>Why?</p><p>Because a client should not reuse the same idempotency key for a different payment request.</p><p>This should be allowed:</p><pre>Same key + same payload = return same result</pre><p>This should not be allowed:</p><pre>Same key + different payload = reject as conflict</pre><p>For example, this is dangerous:</p><pre>Idempotency-Key: abc-123</pre><pre>{<br>  &quot;orderId&quot;: &quot;ORD-1001&quot;,<br>  &quot;amount&quot;: 2499.00<br>}</pre><p>Then later:</p><pre>Idempotency-Key: abc-123</pre><pre>{<br>  &quot;orderId&quot;: &quot;ORD-2002&quot;,<br>  &quot;amount&quot;: 9999.00<br>}</pre><p>The key is the same, but the operation is different.</p><p>A good idempotency implementation should detect this and return a conflict error.</p><pre>409 Conflict</pre><p>The backend can respond with a message like:</p><pre>{<br>  &quot;error&quot;: &quot;Idempotency key was already used with a different request payload&quot;<br>}</pre><p>This protects the system from accidental or incorrect key reuse.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EL6pc6Z42qWc0HfVjKvCow.png" /></figure><h3>Architecture design</h3><p>From an architect’s perspective, idempotency is not just a controller-level validation.</p><p>It is a reliability pattern.</p><p>A proper idempotency design should answer several questions:</p><p>Where is the key stored?</p><p>How long is the key stored?</p><p>What happens if the same key arrives while the first request is still processing?</p><p>What happens if the same key is reused with a different payload?</p><p>Should we store the full response or only the resource ID?</p><p>How do we protect against concurrent requests?</p><p>How do we clean old keys?</p><p>How do we make this work across multiple application instances?</p><p>A production-style architecture usually has these components:</p><pre>Client<br>  |<br>  | POST /payments/initiate<br>  | Idempotency-Key: xyz<br>  v<br>API Controller<br>  |<br>  v<br>Idempotency Service<br>  |<br>  |-- check existing key<br>  |-- validate request hash<br>  |-- reserve key if new<br>  |<br>  v<br>Payment Service<br>  |<br>  |-- create payment<br>  |-- update order status<br>  |-- create audit event<br>  |<br>  v<br>Database</pre><p>The most important part is that the idempotency record must be stored in a durable place.</p><p>For payment systems, a relational database like PostgreSQL is often a strong choice because it can provide:</p><p>Durability</p><p>Transactions</p><p>Unique constraints</p><p>Consistency</p><p>Auditability</p><p>A distributed cache can also be used in some systems, but for payment initiation, database-backed idempotency is easier to reason about because losing the key after an application restart can create duplicate payment risk.</p><p>A strong idempotency architecture usually stores:</p><p>Idempotency key</p><p>Request hash</p><p>Status</p><p>Resource type</p><p>Resource ID</p><p>HTTP status code</p><p>Response body</p><p>Created time</p><p>Expiry time</p><p>This allows the system to return the same result when the client retries.</p><p>The status can be useful for handling in-progress requests.</p><p>For example:</p><pre>IN_PROGRESS<br>COMPLETED<br>FAILED<br>EXPIRED</pre><p>If a duplicate request arrives while the first request is still processing, the API should not start another payment. It can return a response like:</p><pre>409 Conflict</pre><p>or</p><pre>202 Accepted</pre><p>depending on the API design.</p><p>The key idea is simple:</p><blockquote><em>The first request owns the operation. Duplicate requests should observe the result, not repeat the work.</em></blockquote><h3>Spring Boot implementation</h3><p>Let’s now look at how this can be implemented in a Spring Boot payment API.</p><p>A payment initiation endpoint may look like this:</p><pre>@PostMapping(&quot;/initiate&quot;)<br>public ResponseEntity&lt;PaymentResponse&gt; initiatePayment(<br>        @RequestHeader(&quot;Idempotency-Key&quot;) String idempotencyKey,<br>        @Valid @RequestBody InitiatePaymentRequest request,<br>        Authentication authentication<br>) {<br>    PaymentResponse response = paymentService.initiatePayment(<br>            request,<br>            authentication.getName(),<br>            idempotencyKey<br>    );<br>return ResponseEntity.ok(response);<br>}</pre><p>The controller should not contain the idempotency logic. It should only receive the key and pass it to the service layer.</p><p>The service layer is where the business rule belongs.</p><p>A simplified service flow can look like this:</p><pre>@Transactional<br>public PaymentResponse initiatePayment(<br>        InitiatePaymentRequest request,<br>        String userEmail,<br>        String idempotencyKey<br>) {<br>    String requestHash = requestHashService.generateHash(request);<br>Optional&lt;IdempotencyRecord&gt; existingRecord =<br>            idempotencyRepository.findByIdempotencyKey(idempotencyKey);<br>    if (existingRecord.isPresent()) {<br>        IdempotencyRecord record = existingRecord.get();<br>        if (!record.getRequestHash().equals(requestHash)) {<br>            throw new IdempotencyConflictException(<br>                    &quot;Idempotency key was already used with a different payload&quot;<br>            );<br>        }<br>        if (record.getStatus() == IdempotencyStatus.COMPLETED) {<br>            return paymentResponseStore.readResponse(record.getResponseBody());<br>        }<br>        if (record.getStatus() == IdempotencyStatus.IN_PROGRESS) {<br>            throw new RequestAlreadyInProgressException(<br>                    &quot;Request is already being processed&quot;<br>            );<br>        }<br>    }<br>    IdempotencyRecord record = idempotencyRepository.save(<br>            IdempotencyRecord.inProgress(idempotencyKey, requestHash)<br>    );<br>    Payment payment = createPayment(request, userEmail);<br>    PaymentResponse response = mapToResponse(payment);<br>    record.markCompleted(<br>            &quot;PAYMENT&quot;,<br>            payment.getPaymentId(),<br>            200,<br>            paymentResponseStore.toJson(response)<br>    );<br>    idempotencyRepository.save(record);<br>    return response;<br>}</pre><p>This code demonstrates the concept, but production systems should also handle database race conditions carefully.</p><p>The entity can look like this:</p><pre>@Entity<br>@Table(<br>    name = &quot;idempotency_keys&quot;,<br>    uniqueConstraints = {<br>        @UniqueConstraint(name = &quot;uk_idempotency_key&quot;, columnNames = &quot;idempotency_key&quot;)<br>    }<br>)<br>public class IdempotencyRecord {<br><br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    @Column(name = &quot;idempotency_key&quot;, nullable = false, unique = true)<br>    private String idempotencyKey;<br>    @Column(name = &quot;request_hash&quot;, nullable = false)<br>    private String requestHash;<br>    @Enumerated(EnumType.STRING)<br>    @Column(nullable = false)<br>    private IdempotencyStatus status;<br>    private String resourceType;<br>    private String resourceId;<br>    private Integer httpStatus;<br>    @Column(columnDefinition = &quot;TEXT&quot;)<br>    private String responseBody;<br>    private LocalDateTime createdAt;<br>    private LocalDateTime expiresAt;<br>}</pre><p>The repository is simple:</p><pre>public interface IdempotencyRepository<br>        extends JpaRepository&lt;IdempotencyRecord, Long&gt; {<br>Optional&lt;IdempotencyRecord&gt; findByIdempotencyKey(String idempotencyKey);<br>}</pre><p>For request hashing, the idea is to convert the request into a stable representation and generate a hash.</p><pre>@Service<br>public class RequestHashService {<br>private final ObjectMapper objectMapper;<br>    public String generateHash(Object request) {<br>        try {<br>            String json = objectMapper.writeValueAsString(request);<br>            MessageDigest digest = MessageDigest.getInstance(&quot;SHA-256&quot;);<br>            byte[] hash = digest.digest(json.getBytes(StandardCharsets.UTF_8));<br>            return HexFormat.of().formatHex(hash);<br>        } catch (Exception ex) {<br>            throw new IllegalStateException(&quot;Failed to generate request hash&quot;, ex);<br>        }<br>    }<br>}</pre><p>In real systems, request hashing must be stable. Field ordering, null handling, default values, and formatting should be consistent. Otherwise, two logically identical requests may generate different hashes.</p><h3>Database table design</h3><p>A good idempotency table is small but important.</p><p>Example schema:</p><pre>CREATE TABLE idempotency_keys (<br>    id BIGSERIAL PRIMARY KEY,<br>    idempotency_key VARCHAR(255) NOT NULL,<br>    request_hash VARCHAR(255) NOT NULL,<br>    status VARCHAR(50) NOT NULL,<br>    resource_type VARCHAR(100),<br>    resource_id VARCHAR(255),<br>    http_status INTEGER,<br>    response_body TEXT,<br>    created_at TIMESTAMP NOT NULL,<br>    expires_at TIMESTAMP NOT NULL,<br>CONSTRAINT uk_idempotency_key UNIQUE (idempotency_key)<br>);</pre><p>The unique constraint is one of the most important parts of the design.</p><p>Without it, two concurrent requests with the same idempotency key may both check the database, both find nothing, and both create separate payments.</p><p>The unique constraint makes the database the final authority.</p><p>The table can be understood like this:</p><pre>ColumnPurposeidempotency_keyUnique key sent by clientrequest_hashFingerprint of request bodystatusIN_PROGRESS, COMPLETED, FAILED, etc.resource_typeExample: PAYMENTresource_idExample: PAY-1001http_statusOriginal response statusresponse_bodyOriginal response payloadcreated_atWhen key was first usedexpires_atWhen key can be cleaned up</pre><p>Some systems store only the resource ID and rebuild the response from the database.</p><p>Other systems store the full response body and return it exactly on retry.</p><p>Both approaches can work.</p><p>Storing only the resource ID is cleaner and avoids large response storage.</p><p>Storing the full response gives the strongest “same request, same response” behavior.</p><p>The right choice depends on the API design.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-Iptql1SMjXcXFj_jomx2w.png" /></figure><h3>Concurrency and race conditions</h3><p>The most common mistake in idempotency implementation is relying only on this logic:</p><pre>1. Check if key exists<br>2. If not, create payment<br>3. Save key</pre><p>This looks correct, but it can fail under concurrency.</p><p>Imagine two identical requests arrive at the same time.</p><pre>Request A checks key -&gt; not found<br>Request B checks key -&gt; not found<br>Request A creates payment PAY-1001<br>Request B creates payment PAY-1002<br>Request A saves key<br>Request B saves key</pre><p>Now the system has two payments.</p><p>This is called a race condition.</p><p>The fix is to make the idempotency key unique at the database level.</p><pre>CONSTRAINT uk_idempotency_key UNIQUE (idempotency_key)</pre><p>Now if two requests try to insert the same key, only one can win.</p><p>The second request must handle the duplicate key error, reload the existing idempotency record, and return the correct response.</p><p>A safer flow is:</p><pre>1. Try to reserve the idempotency key<br>2. If reservation succeeds:<br>      process the payment<br>      store the response<br>3. If reservation fails:<br>      read existing record<br>      return existing result or in-progress response</pre><p>This approach treats the idempotency key as a lock around the business operation.</p><p>For high-scale systems, teams may also use:</p><p>Database unique constraints</p><p>Pessimistic locking</p><p>Optimistic locking</p><p>Distributed locks</p><p>Message deduplication</p><p>Outbox pattern</p><p>Exactly-once-like processing patterns</p><p>But the foundation is still the same:</p><blockquote><em>Never trust “check then insert” without a uniqueness guarantee.</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eTwrSsWinsL4vMHoLb3NjA.png" /></figure><h3>Best practices</h3><p>Here are practical best practices for idempotency keys in payment APIs.</p><h3>1. Require the key for critical POST APIs</h3><p>For payment initiation, refund creation, wallet transfers, and similar operations, make the idempotency key mandatory.</p><pre>Idempotency-Key: &lt;unique-client-generated-key&gt;</pre><p>If the key is missing, return a validation error.</p><pre>400 Bad Request</pre><h3>2. Generate the key on the client side</h3><p>The client should generate one key per logical operation.</p><p>For example, one payment attempt should have one key.</p><p>If the request is retried, the same key should be reused.</p><p>If the user starts a new payment attempt, a new key should be generated.</p><h3>3. Store a request hash</h3><p>Always store a fingerprint of the request payload.</p><p>This prevents the same idempotency key from being reused for a different request.</p><p>Same key and same hash should return the same result.</p><p>Same key and different hash should return a conflict.</p><h3>4. Use a database unique constraint</h3><p>Do not rely only on application-level checks.</p><p>In distributed systems, multiple app instances may process the same key at the same time.</p><p>The database must enforce uniqueness.</p><h3>5. Store enough information to return the same result</h3><p>You can store the full response or store the resource ID and reconstruct the response.</p><p>But duplicate requests should not create new business operations.</p><h3>6. Handle in-progress requests</h3><p>If the first request is still processing and the duplicate request arrives, do not start another operation.</p><p>Return a meaningful response such as:</p><pre>409 Conflict</pre><p>or</p><pre>202 Accepted</pre><h3>7. Add expiry or cleanup</h3><p>Idempotency keys should not stay forever unless there is a compliance reason.</p><p>Add an expiry time and clean up old records using a scheduled job.</p><h3>8. Do not use idempotency as a replacement for business validation</h3><p>Idempotency prevents duplicate execution of the same request.</p><p>It does not replace:</p><p>Authentication</p><p>Authorization</p><p>Order ownership validation</p><p>Payment state validation</p><p>Fraud checks</p><p>Amount validation</p><p>Rate limiting</p><p>Audit logging</p><p>It is one layer in a reliable payment architecture.</p><h3>9. Apply idempotency to webhooks too</h3><p>Payment providers may send the same webhook multiple times.</p><p>Webhook handlers should also be idempotent.</p><p>If a payment_success webhook is received twice, the second webhook should not create duplicate notifications or duplicate audit records.</p><h3>10. Log idempotency decisions</h3><p>For debugging production issues, log important idempotency events:</p><p>New key reserved</p><p>Duplicate key detected</p><p>Payload hash mismatch</p><p>In-progress duplicate request</p><p>Completed response returned</p><p>Expired key cleanup</p><p>These logs are very useful when investigating payment disputes.</p><h3>Interview questions and answers</h3><h3>Q1. What is idempotency?</h3><p>Idempotency means performing the same operation multiple times has the same effect as performing it once.</p><p>In payment APIs, it means retrying the same payment request should not create duplicate payments.</p><h3>Q2. What is an idempotency key?</h3><p>An idempotency key is a unique value sent by the client with a request. The server stores this key and uses it to detect duplicate requests.</p><p>If the same key is received again, the server returns the original result instead of repeating the operation.</p><h3>Q3. Why are idempotency keys important in payment systems?</h3><p>Because payment systems commonly face retries, timeouts, duplicate clicks, gateway retries, and webhook redelivery.</p><p>Without idempotency, the same payment request can be processed more than once, causing duplicate charges or duplicate records.</p><h3>Q4. Is POST idempotent?</h3><p>No, POST is not idempotent by default.</p><p>But a specific POST endpoint can be designed to behave idempotently by using an idempotency key.</p><h3>Q5. Where should idempotency keys be stored?</h3><p>They should be stored in a durable store.</p><p>For payment APIs, a relational database is a good choice because it supports transactions, durability, and unique constraints.</p><p>Some systems may use distributed caches, but the design must ensure keys are not lost during failures.</p><h3>Q6. What happens if the same key is reused with a different payload?</h3><p>The server should reject the request, usually with 409 Conflict.</p><p>The same idempotency key should represent the same business operation, not a different request.</p><h3>Q7. Why do we need a request hash?</h3><p>A request hash helps the server verify that retries with the same idempotency key are actually the same request.</p><p>It prevents accidental or malicious reuse of the same key with different payloads.</p><h3>Q8. What is the biggest concurrency risk?</h3><p>The biggest risk is two requests with the same idempotency key arriving at the same time.</p><p>If the system only does “check then insert,” both requests may create separate payments.</p><p>A database unique constraint on the idempotency key is essential.</p><h3>Q9. Should we store the full response?</h3><p>It depends.</p><p>Storing the full response makes it easy to return exactly the same result.</p><p>Storing only the resource ID is cleaner and allows the response to be rebuilt from current data.</p><p>For payment APIs, either approach can work if duplicate requests do not repeat the side effect.</p><h3>Q10. Is idempotency only needed for payments?</h3><p>No.</p><p>Idempotency is useful for any operation where duplicate execution is harmful.</p><p>Examples include order placement, refunds, wallet transfers, subscription creation, invoice generation, webhook processing, and message consumers.</p><h3>Final thoughts</h3><p>In payment systems, retries are not bugs.</p><p>They are part of the reality of distributed systems.</p><p>Networks fail. Clients retry. Gateways resend. Users double-click. Webhooks are delivered more than once.</p><p>A reliable payment API should not assume that every request arrives exactly once.</p><p>It should assume the opposite:</p><blockquote><em>The same request may arrive multiple times.</em></blockquote><p>An idempotency key gives the backend a simple but powerful way to handle that reality.</p><p>It turns a dangerous retry into a safe retry.</p><p>It protects customers from duplicate charges.</p><p>It protects businesses from payment disputes.</p><p>It protects engineers from painful production incidents.</p><p>And from an architecture perspective, it shows maturity.</p><p>Because building a payment API is not only about creating a payment record.</p><p>It is about handling failure, retries, duplicates, concurrency, and consistency.</p><p>That is why the idempotency key matters.</p><p>It may look like just another HTTP header.</p><p>But in payment APIs, it is the small header that prevents double charges.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b76c1ceb0066" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[HTTP QUERY: The Missing Method Between GET and POST]]></title>
            <link>https://medium.com/@balmikprajapati53/http-query-the-missing-method-between-get-and-post-8c7e14ee071c?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/8c7e14ee071c</guid>
            <category><![CDATA[backend-development]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[https]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[api-design]]></category>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Sun, 26 Jul 2026 11:14:13 GMT</pubDate>
            <atom:updated>2026-07-26T11:14:13.964Z</atom:updated>
            <content:encoded><![CDATA[<p>For years, API designers have had an awkward choice.</p><p>When the operation is a simple read, GET is the obvious answer.</p><pre>GET /orders?status=PAID&amp;customerId=123</pre><p>It is simple, familiar, safe, idempotent, cache-friendly, and easy to test from a browser or command line.</p><p>But real-world APIs rarely stay that simple.</p><p>Search pages grow more advanced. Filters become nested. Reporting APIs need date ranges, sorting rules, pagination, grouping, permissions, and multiple optional criteria. Product catalogs need faceted search. Order systems need complex business filters. Analytics APIs need structured query input. At some point, the clean GET URL starts becoming long, hard to read, difficult to encode, and fragile across gateways, proxies, clients, and logs.</p><p>So teams often reach for the workaround everyone understands:</p><pre>POST /orders/search Content-Type: application/json</pre><pre>{ &quot;status&quot;: &quot;PAID&quot;, &quot;customerId&quot;: &quot;123&quot;, &quot;dateRange&quot;: { &quot;from&quot;: &quot;2026-01-01&quot;, &quot;to&quot;: &quot;2026-01-31&quot; }, &quot;sort&quot;: [ { &quot;field&quot;: &quot;createdAt&quot;, &quot;direction&quot;: &quot;desc&quot; } ], &quot;page&quot;: 1, &quot;size&quot;: 50 }</pre><p>Technically, this works.</p><p>Practically, this pattern is everywhere.</p><p>Semantically, however, it has always felt slightly wrong.</p><p>The client is not creating an order. It is not updating a resource. It is not triggering a workflow. It is not changing server state. It is simply asking a question: “Give me the orders that match these criteria.”</p><p>But because the request body is complex, we use POST.</p><p>That is the gap the HTTP QUERY method is designed to fill.</p><p>QUERY gives API designers a method that sits between GET and POST: a way to send structured query content in the request body while still expressing that the operation is safe and idempotent.</p><p>In other words:</p><pre>QUERY /orders Content-Type: application/json</pre><pre>{ &quot;status&quot;: &quot;PAID&quot;, &quot;customerId&quot;: &quot;123&quot;, &quot;dateRange&quot;: { &quot;from&quot;: &quot;2026-01-01&quot;, &quot;to&quot;: &quot;2026-01-31&quot; }, &quot;sort&quot;: [ { &quot;field&quot;: &quot;createdAt&quot;, &quot;direction&quot;: &quot;desc&quot; } ], &quot;page&quot;: 1, &quot;size&quot;: 50 }</pre><p>This looks similar to POST, but it means something different.</p><p>A QUERY request says:</p><blockquote><em>Process this request content as a query and return the result, without changing the state of the target resource.</em></blockquote><p>That distinction matters because HTTP methods are not just syntax. They communicate intent to clients, servers, gateways, caches, load balancers, observability tools, SDKs, and developers.</p><p>QUERY is HTTP finally saying: complex read operations deserve their own method.</p><h3>The problem with GET for complex queries</h3><p>GET is still the best method for simple read operations.</p><p>For example:</p><pre>GET /products?category=laptop&amp;brand=Dell</pre><p>This is readable, bookmarkable, cacheable, and easy to reason about.</p><p>But as query requirements grow, GET becomes uncomfortable.</p><p>Imagine a product search API with filters like this:</p><pre>{<br>  &quot;filters&quot;: {<br>    &quot;category&quot;: &quot;laptop&quot;,<br>    &quot;price&quot;: {<br>      &quot;min&quot;: 500,<br>      &quot;max&quot;: 1500<br>    },<br>    &quot;brands&quot;: [&quot;Dell&quot;, &quot;Lenovo&quot;, &quot;HP&quot;],<br>    &quot;specifications&quot;: {<br>      &quot;ram&quot;: [&quot;16GB&quot;, &quot;32GB&quot;],<br>      &quot;storage&quot;: [&quot;512GB SSD&quot;, &quot;1TB SSD&quot;],<br>      &quot;processor&quot;: [&quot;i5&quot;, &quot;i7&quot;, &quot;Ryzen 7&quot;]<br>    },<br>    &quot;availability&quot;: {<br>      &quot;inStock&quot;: true,<br>      &quot;deliveryDateBefore&quot;: &quot;2026-02-01&quot;<br>    }<br>  },<br>  &quot;sort&quot;: [<br>    {<br>      &quot;field&quot;: &quot;rating&quot;,<br>      &quot;direction&quot;: &quot;desc&quot;<br>    },<br>    {<br>      &quot;field&quot;: &quot;price&quot;,<br>      &quot;direction&quot;: &quot;asc&quot;<br>    }<br>  ],<br>  &quot;page&quot;: 1,<br>  &quot;size&quot;: 20<br>}</pre><p>Encoding this cleanly into a URL is possible, but it is not pleasant.</p><p>You end up with long query strings, repeated parameters, custom encoding rules, or compressed query formats that only your team understands.</p><p>That creates several problems:</p><p>Long URLs can hit limits across clients, gateways, proxies, servers, or monitoring tools.</p><p>Nested data structures are awkward to represent in query parameters.</p><p>Sensitive or semi-sensitive filter criteria are more likely to appear in logs, browser history, bookmarks, and analytics tools when placed in the URL.</p><p>Different teams may invent different conventions for arrays, nested objects, ranges, and sorting.</p><p>The API contract becomes harder to read and harder to document.</p><p>This is why many teams move complex searches away from GET.</p><p>But the usual alternative, POST, introduces a different problem.</p><h3>The problem with POST for read-only queries</h3><p>POST is flexible. It allows a request body. It is widely supported. Every framework, gateway, API client, and testing tool understands it.</p><p>That is why POST /search became such a common pattern.</p><pre>POST /products/search<br>Content-Type: application/json</pre><p>From an implementation point of view, this is easy.</p><p>From an HTTP semantics point of view, it is less precise.</p><p>POST does not clearly tell infrastructure or developers that the operation is safe and idempotent. A POST request might create a payment, submit an order, trigger an email, start a workflow, or run a report. Without knowing the specific endpoint behavior, a client cannot safely assume that repeating the request has no side effects.</p><p>That matters for retry logic.</p><p>It matters for caching.</p><p>It matters for API observability.</p><p>It matters for documentation.</p><p>It matters for developer expectations.</p><p>When an API uses POST /orders/search, the route name says “search,” but the HTTP method says “this may change something.”</p><p>For many systems, that mismatch is tolerated because the ecosystem has not had a better standard method for complex read-only operations.</p><p>Now it does.</p><h3>What is HTTP QUERY?</h3><p>HTTP QUERY is a method for safe, idempotent server-side query operations that need request content.</p><p>In simple terms:</p><p>GET is for retrieving a resource representation.</p><p>POST is for submitting content for processing, often with possible side effects.</p><p>QUERY is for asking a resource to process query content and return a result safely and idempotently.</p><p>A typical QUERY request looks like this:</p><pre>QUERY /orders HTTP/1.1<br>Host: api.example.com<br>Content-Type: application/json<br>Accept: application/json</pre><pre>{<br>  &quot;status&quot;: &quot;PAID&quot;,<br>  &quot;from&quot;: &quot;2026-01-01&quot;,<br>  &quot;to&quot;: &quot;2026-01-31&quot;<br>}</pre><p>And the response could look like this:</p><pre>HTTP/1.1 200 OK<br>Content-Type: application/json</pre><pre>{<br>  &quot;items&quot;: [<br>    {<br>      &quot;orderId&quot;: &quot;ORD-1001&quot;,<br>      &quot;status&quot;: &quot;PAID&quot;,<br>      &quot;total&quot;: 249.99<br>    },<br>    {<br>      &quot;orderId&quot;: &quot;ORD-1002&quot;,<br>      &quot;status&quot;: &quot;PAID&quot;,<br>      &quot;total&quot;: 119.50<br>    }<br>  ],<br>  &quot;page&quot;: 1,<br>  &quot;size&quot;: 50,<br>  &quot;total&quot;: 2<br>}</pre><p>The important idea is that the query criteria live in the request body, but the method still communicates read-only intent.</p><p>That makes QUERY especially useful for APIs where the operation is logically a read, but the input is too complex for a clean URL.</p><h3>GET vs POST vs QUERY</h3><p>Here is a practical way to think about the three methods.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fcVrtf-TTufULQPgD373Ww.png" /></figure><p>This does not mean QUERY replaces GET.</p><p>For simple reads, GET is still the better default.</p><p>Use this:</p><pre>GET /customers/123</pre><p>Not this:</p><pre>QUERY /customers/123<br>Content-Type: application/json</pre><pre>{}</pre><p>Use QUERY when the request is still read-only, but the query input deserves a real body.</p><h3>A better API design for search endpoints</h3><p>Many APIs today expose search like this:</p><pre>POST /orders/search<br>Content-Type: application/json</pre><p>With QUERY, the API can be designed around the resource itself:</p><pre>QUERY /orders<br>Content-Type: application/json</pre><p>This is cleaner for two reasons.</p><p>First, the method already says this is a query. You do not need to encode the operation into the path with /search.</p><p>Second, the target resource remains meaningful. You are querying the orders collection. The request body describes how to query it.</p><p>For example:</p><pre>QUERY /orders<br>Content-Type: application/json<br>Accept: application/json</pre><pre>{<br>  &quot;filters&quot;: {<br>    &quot;status&quot;: [&quot;PAID&quot;, &quot;SHIPPED&quot;],<br>    &quot;customerType&quot;: &quot;PREMIUM&quot;,<br>    &quot;createdAt&quot;: {<br>      &quot;from&quot;: &quot;2026-01-01&quot;,<br>      &quot;to&quot;: &quot;2026-01-31&quot;<br>    }<br>  },<br>  &quot;sort&quot;: [<br>    {<br>      &quot;field&quot;: &quot;createdAt&quot;,<br>      &quot;direction&quot;: &quot;desc&quot;<br>    }<br>  ],<br>  &quot;page&quot;: {<br>    &quot;number&quot;: 1,<br>    &quot;size&quot;: 50<br>  }<br>}</pre><p>The API reads naturally:</p><blockquote><em>Query the orders resource using these criteria.</em></blockquote><p>That is more expressive than:</p><pre>POST /orders/search</pre><p>Because now both the method and the path are doing the right job.</p><h3>When should you use QUERY?</h3><p>QUERY is a good fit when all of these are true:</p><p>The operation is read-only.</p><p>The operation is safe to retry.</p><p>The query input is too large, nested, or structured for a clean URL.</p><p>The request body represents query criteria, not a command.</p><p>The response is the result of evaluating that query.</p><p>Good examples include:</p><p>Advanced search APIs.</p><p>Reporting and analytics filters.</p><p>Product catalog filtering.</p><p>Order search.</p><p>Audit log queries.</p><p>Graph-style lookup APIs.</p><p>Complex permission-aware queries.</p><p>Event or transaction search.</p><p>Observability query APIs.</p><p>Customer support dashboards.</p><p>For example, an audit search API might look like this:</p><pre>QUERY /audit-events<br>Content-Type: application/json<br>Accept: application/json</pre><pre>{<br>  &quot;actor&quot;: {<br>    &quot;type&quot;: &quot;USER&quot;,<br>    &quot;id&quot;: &quot;u-123&quot;<br>  },<br>  &quot;actions&quot;: [&quot;LOGIN_FAILED&quot;, &quot;PASSWORD_CHANGED&quot;],<br>  &quot;timeRange&quot;: {<br>    &quot;from&quot;: &quot;2026-01-01T00:00:00Z&quot;,<br>    &quot;to&quot;: &quot;2026-01-31T23:59:59Z&quot;<br>  },<br>  &quot;includeMetadata&quot;: true,<br>  &quot;page&quot;: {<br>    &quot;size&quot;: 100<br>  }<br>}</pre><p>This is much easier to read and maintain than forcing the same structure into query parameters.</p><h3>When should you not use QUERY?</h3><p>QUERY is not a replacement for every API method.</p><p>Do not use QUERY for operations that create, update, delete, approve, submit, reserve, charge, publish, or trigger something.</p><p>These should not be QUERY:</p><pre>QUERY /payments</pre><pre>QUERY /orders/123/cancel</pre><pre>QUERY /emails/send</pre><pre>QUERY /inventory/reservations</pre><p>Even if the request body looks like a query, the operation changes system state. That belongs to POST, PUT, PATCH, or DELETE, depending on the design.</p><p>Also, do not replace simple GET endpoints just because QUERY exists.</p><p>This should remain a GET:</p><pre>GET /orders/ORD-1001</pre><p>This should also probably remain a GET:</p><pre>GET /orders?status=PAID</pre><p>The best rule is simple:</p><p>Use GET for simple reads.</p><p>Use QUERY for complex read-only queries.</p><p>Use POST when the server is processing a command or creating side effects.</p><h3>Why QUERY matters beyond syntax</h3><p>At first, QUERY might look like a small addition.</p><p>After all, teams already use POST /search. Why bother changing?</p><p>The answer is that HTTP semantics affect more than controller code.</p><p>They influence the behavior and assumptions of the entire delivery path.</p><p>A safe and idempotent method can be retried more confidently after network failures.</p><p>Monitoring tools can classify traffic more accurately.</p><p>API documentation can express intent more clearly.</p><p>Gateways and intermediaries can make better decisions.</p><p>Caching strategies can become more explicit.</p><p>Developers can understand an endpoint faster.</p><p>Security reviews can distinguish read-only query traffic from mutation traffic.</p><p>This is the same reason we do not use POST for everything, even though we technically could.</p><p>HTTP methods are part of the API contract.</p><p>A good API does not only work. It communicates.</p><h3>What about caching?</h3><p>One of the interesting parts of QUERY is caching.</p><p>With GET, caching is relatively natural because the URI identifies the request. The cache key usually includes the method, scheme, host, path, and query string, along with relevant headers.</p><p>With QUERY, the request body also matters.</p><p>That means a cache cannot treat every request to /orders as equivalent. It must consider the query content and related metadata, such as Content-Type.</p><p>For example, these two requests are not the same:</p><pre>QUERY /orders<br>Content-Type: application/json</pre><pre>{<br>  &quot;status&quot;: &quot;PAID&quot;<br>}</pre><pre>QUERY /orders<br>Content-Type: application/json</pre><pre>{<br>  &quot;status&quot;: &quot;CANCELLED&quot;<br>}</pre><p>A correct cache must distinguish them.</p><p>This makes QUERY caching more complex than GET caching, but the semantics are still useful. In practice, many teams may start by using QUERY for better API correctness and observability before relying heavily on intermediary caching.</p><p>A server can also help by returning a Location or Content-Location header when it wants to expose a URI that can later be retrieved with GET.</p><p>For example:</p><pre>HTTP/1.1 200 OK<br>Content-Type: application/json<br>Content-Location: /orders/query-results/abc123</pre><pre>{<br>  &quot;items&quot;: []<br>}</pre><p>Or:</p><pre>HTTP/1.1 201 Created<br>Location: /orders/stored-queries/monthly-paid-orders</pre><p>This gives the server a way to bridge complex query submission and later URI-based retrieval.</p><h3>How clients can discover QUERY support</h3><p>A server can advertise support for QUERY using response headers.</p><p>For example:</p><pre>HTTP/1.1 204 No Content<br>Allow: GET, QUERY, OPTIONS<br>Accept-Query: application/json</pre><p>The Allow header tells the client that QUERY is supported for the resource.</p><p>The Accept-Query header tells the client which query content types are accepted.</p><p>For example:</p><pre>Accept-Query: application/json</pre><p>Or, for a more specialized API:</p><pre>Accept-Query: application/sql</pre><p>This is important because QUERY is not just “GET with a body.” The request content has semantics defined by the target resource and the media type.</p><p>A JSON query body, SQL query body, JSONPath query body, or custom domain-specific query format can all mean different things.</p><p>The server should be explicit about what it accepts.</p><h3>Error handling for QUERY APIs</h3><p>A well-designed QUERY endpoint should be strict about content type and validation.</p><p>If the request does not include a Content-Type, the server should reject it.</p><pre>HTTP/1.1 400 Bad Request<br>Content-Type: application/json</pre><pre>{<br>  &quot;error&quot;: &quot;Content-Type is required for QUERY requests&quot;<br>}</pre><p>If the content type is not supported, return 415 Unsupported Media Type.</p><pre>HTTP/1.1 415 Unsupported Media Type<br>Accept-Query: application/json<br>Content-Type: application/json</pre><pre>{<br>  &quot;error&quot;: &quot;This endpoint accepts QUERY requests with application/json only&quot;<br>}</pre><p>If the JSON is valid but the query itself is not processable, return 422 Unprocessable Content.</p><pre>HTTP/1.1 422 Unprocessable Content<br>Content-Type: application/json</pre><pre>{<br>  &quot;error&quot;: &quot;Invalid date range&quot;,<br>  &quot;details&quot;: &quot;from must be before to&quot;<br>}</pre><p>If the client asks for a response format the server cannot produce, return 406 Not Acceptable.</p><pre>HTTP/1.1 406 Not Acceptable<br>Content-Type: application/json</pre><pre>{<br>  &quot;error&quot;: &quot;Only application/json responses are supported&quot;<br>}</pre><p>This makes the API predictable and easier to integrate.</p><h3>A Spring Boot perspective</h3><p>For Java and Spring Boot teams, QUERY is especially interesting because many enterprise APIs already use patterns like:</p><pre>POST /customers/search<br>POST /orders/filter<br>POST /transactions/query<br>POST /reports/run</pre><p>Some of these are truly commands.</p><p>But many are read-only queries hiding behind POST.</p><p>A future Spring Boot application might ideally expose something like:</p><pre>@QueryMapping(&quot;/orders&quot;)<br>public OrderSearchResponse queryOrders(@RequestBody OrderSearchRequest request) {<br>    return orderSearchService.search(request);<br>}</pre><p>But framework support for new HTTP methods does not appear everywhere overnight.</p><p>Today, many Spring MVC applications are built around method enums such as GET, POST, PUT, PATCH, and DELETE. That means you should not assume that a standard annotation-based controller can support QUERY in the same way it supports GET or POST.</p><p>For experimentation, a low-level servlet adapter can demonstrate the idea.</p><pre>@Configuration<br>public class QueryServletConfig {</pre><pre>    @Bean<br>    public ServletRegistrationBean&lt;HttpServlet&gt; orderQueryServlet(<br>            OrderQueryService orderQueryService,<br>            ObjectMapper objectMapper<br>    ) {<br>        HttpServlet servlet = new HttpServlet() {<br>            @Override<br>            protected void service(<br>                    HttpServletRequest request,<br>                    HttpServletResponse response<br>            ) throws IOException {</pre><pre>                if (!&quot;QUERY&quot;.equalsIgnoreCase(request.getMethod())) {<br>                    response.setStatus(HttpServletResponse.SC_METHOD_NOT_ALLOWED);<br>                    response.setHeader(&quot;Allow&quot;, &quot;QUERY&quot;);<br>                    return;<br>                }</pre><pre>                String contentType = request.getContentType();</pre><pre>                if (contentType == null || !contentType.startsWith(&quot;application/json&quot;)) {<br>                    response.setStatus(HttpServletResponse.SC_UNSUPPORTED_MEDIA_TYPE);<br>                    response.setHeader(&quot;Accept-Query&quot;, &quot;application/json&quot;);<br>                    response.setContentType(&quot;application/json&quot;);<br>                    response.getWriter().write(&quot;&quot;&quot;<br>                        {<br>                          &quot;error&quot;: &quot;QUERY requests to /orders require application/json&quot;<br>                        }<br>                        &quot;&quot;&quot;);<br>                    return;<br>                }</pre><pre>                OrderQueryRequest queryRequest =<br>                        objectMapper.readValue(request.getInputStream(), OrderQueryRequest.class);</pre><pre>                OrderQueryResponse result =<br>                        orderQueryService.search(queryRequest);</pre><pre>                response.setStatus(HttpServletResponse.SC_OK);<br>                response.setContentType(&quot;application/json&quot;);<br>                response.setHeader(&quot;Accept-Query&quot;, &quot;application/json&quot;);</pre><pre>                objectMapper.writeValue(response.getOutputStream(), result);<br>            }<br>        };</pre><pre>        return new ServletRegistrationBean&lt;&gt;(servlet, &quot;/orders&quot;);<br>    }<br>}</pre><p>The request model could look like this:</p><pre>public record OrderQueryRequest(<br>        List&lt;String&gt; statuses,<br>        DateRange dateRange,<br>        List&lt;SortField&gt; sort,<br>        PageRequest page<br>) {<br>}</pre><pre>public record DateRange(<br>        LocalDate from,<br>        LocalDate to<br>) {<br>}</pre><pre>public record SortField(<br>        String field,<br>        String direction<br>) {<br>}</pre><p>And the request can be tested with curl:</p><pre>curl -X QUERY &quot;http://localhost:8080/orders&quot; \<br>  -H &quot;Content-Type: application/json&quot; \<br>  -H &quot;Accept: application/json&quot; \<br>  -d &#39;{<br>    &quot;statuses&quot;: [&quot;PAID&quot;, &quot;SHIPPED&quot;],<br>    &quot;dateRange&quot;: {<br>      &quot;from&quot;: &quot;2026-01-01&quot;,<br>      &quot;to&quot;: &quot;2026-01-31&quot;<br>    },<br>    &quot;sort&quot;: [<br>      {<br>        &quot;field&quot;: &quot;createdAt&quot;,<br>        &quot;direction&quot;: &quot;desc&quot;<br>      }<br>    ],<br>    &quot;page&quot;: {<br>      &quot;number&quot;: 1,<br>      &quot;size&quot;: 50<br>    }<br>  }&#39;</pre><p>This is not necessarily how every production Spring Boot application should implement QUERY.</p><p>It is a starting point.</p><p>Before using QUERY in production, teams should validate the full request path:</p><p>Client library support.</p><p>Browser and CORS behavior.</p><p>API gateway support.</p><p>Load balancer behavior.</p><p>WAF rules.</p><p>Reverse proxy configuration.</p><p>Application framework routing.</p><p>OpenAPI or API documentation tooling.</p><p>Logging and tracing.</p><p>Caching behavior.</p><p>Monitoring dashboards.</p><p>Retry policies.</p><p>Contract testing.</p><p>In other words, QUERY is not just a controller change. It is an API platform decision.</p><h3>A realistic migration strategy</h3><p>Most teams should not rush to replace every POST /search endpoint immediately.</p><p>A safer migration strategy is incremental.</p><p>Start with internal APIs or non-critical read-only search endpoints.</p><p>Pick one endpoint where the semantics are clearly read-only and the request body is already being used only for filtering.</p><p>For example:</p><pre>POST /orders/search</pre><p>Introduce the new method alongside the existing endpoint:</p><pre>QUERY /orders</pre><p>Keep both endpoints temporarily.</p><p>Document the difference clearly.</p><p>Add observability so you can compare usage.</p><p>Test behavior through every gateway and proxy.</p><p>Update SDKs and internal clients.</p><p>Only then consider deprecating the old POST /search route.</p><p>For external APIs, migration needs even more care. Many clients, proxies, SDK generators, and API tools may not yet fully understand QUERY. In those cases, keeping POST /search as a compatibility fallback may be the right decision for a long time.</p><p>Adoption will likely be gradual.</p><p>That does not make QUERY unimportant.</p><p>It means QUERY is a new semantic tool that API designers can start using where the ecosystem allows it.</p><h3>QUERY and API design clarity</h3><p>The biggest benefit of QUERY may not be technical performance.</p><p>It may be clarity.</p><p>Consider these three endpoints:</p><pre>GET /orders?status=PAID</pre><pre>POST /orders/search</pre><pre>QUERY /orders</pre><p>The first is great for simple filtering.</p><p>The second works, but it encodes a read operation as a post.</p><p>The third clearly says: query the orders resource using the enclosed query content.</p><p>That is clean API design.</p><p>It aligns the method, the path, and the operation.</p><p>This is especially valuable in large organizations where APIs are consumed by many teams. Developers should not need tribal knowledge to understand whether a request is safe to retry. The method should communicate that.</p><h3>Security considerations</h3><p>QUERY can reduce some problems caused by putting large or sensitive query criteria into URLs, but it does not automatically make query data private.</p><p>Request bodies can still be logged.</p><p>Gateways can still inspect them.</p><p>Application logs can still accidentally capture them.</p><p>Tracing tools can still record payloads if configured poorly.</p><p>So the right security lesson is not:</p><blockquote><em>Put sensitive data in QUERY and everything is safe.</em></blockquote><p>The better lesson is:</p><blockquote><em>Avoid exposing sensitive query data in URLs, and apply proper logging, redaction, authorization, and retention controls wherever the data travels.</em></blockquote><p>Teams should define clear rules for:</p><p>Which fields can appear in query bodies.</p><p>Which fields must be redacted from logs.</p><p>Whether query requests can be cached.</p><p>How long query results can be stored.</p><p>Whether generated result URIs can expose sensitive information.</p><p>How authorization is enforced before processing the query.</p><p>A safe HTTP method does not remove the need for security design.</p><p>It simply means the client is not asking the server to change the target resource.</p><h3>Practical guidelines</h3><p>Here is the simplest decision framework.</p><p>Use GET when the request is a simple read and the query fits naturally in the URL.</p><pre>GET /orders?status=PAID</pre><p>Use QUERY when the request is read-only but the query criteria are structured, nested, large, or better represented as a request body.</p><pre>QUERY /orders<br>Content-Type: application/json</pre><p>Use POST when the request submits a command, creates a resource, triggers processing, or may cause side effects.</p><pre>POST /orders<br>Content-Type: application/json</pre><p>Use PUT when replacing a resource.</p><pre>PUT /customers/123<br>Content-Type: application/json</pre><p>Use PATCH when partially updating a resource.</p><pre>PATCH /customers/123<br>Content-Type: application/json</pre><p>Use DELETE when removing a resource.</p><pre>DELETE /customers/123</pre><p>The key is not to choose the method based only on whether you need a request body.</p><p>Choose the method based on intent.</p><p>That is exactly where QUERY helps.</p><h3>Production readiness checklist</h3><p>Before adopting QUERY, ask these questions:</p><p>Does our API gateway allow the QUERY method?</p><p>Does our load balancer forward it correctly?</p><p>Does our WAF block unknown or newer HTTP methods?</p><p>Do our clients support custom HTTP methods?</p><p>Do our SDK generators support it?</p><p>Does our API documentation tool support it?</p><p>Does our observability stack classify it correctly?</p><p>Do our logs capture query bodies safely?</p><p>Do our caching layers handle request-body-based cache keys correctly?</p><p>Does our CORS configuration allow it where needed?</p><p>Do our retry policies treat it as safe and idempotent?</p><p>Do our contract tests cover it?</p><p>Do we need a POST /search fallback for older clients?</p><p>These questions are not reasons to avoid QUERY.</p><p>They are reasons to adopt it deliberately.</p><h3>Final thoughts</h3><p>HTTP QUERY fills a gap API developers have worked around for years.</p><p>GET is excellent for simple reads, but it becomes awkward when query criteria are large or deeply structured.</p><p>POST supports request bodies, but it does not clearly communicate safe, idempotent, read-only intent.</p><p>QUERY gives us a better option.</p><p>It lets API designers model complex read operations honestly:</p><pre>QUERY /orders<br>Content-Type: application/json</pre><p>That one line communicates a lot.</p><p>It says the target resource is orders.</p><p>It says the request body contains query criteria.</p><p>It says the operation is safe.</p><p>It says the operation is idempotent.</p><p>It says this is not a command disguised as a search endpoint.</p><p>Will every framework, gateway, proxy, and client support it immediately? No.</p><p>Will adoption take time? Yes.</p><p>But the direction is important.</p><p>For years, many APIs used POST /search not because it was the best semantic choice, but because HTTP did not give us a widely standardized method for complex read-only queries with a body.</p><p>Now it does.</p><p>And for modern API design, that is a meaningful step forward.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8c7e14ee071c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Looping Is the Missing Layer in AI Workflows]]></title>
            <link>https://medium.com/@balmikprajapati53/looping-is-the-missing-layer-in-ai-workflows-af2130360c84?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/af2130360c84</guid>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Sun, 28 Jun 2026 12:20:09 GMT</pubDate>
            <atom:updated>2026-06-28T14:07:25.827Z</atom:updated>
            <content:encoded><![CDATA[<p>Why the future of AI is not just better prompts, but better feedback systems.</p><p><strong>Introduction: Why One Prompt Is No Longer Enough</strong></p><p>For a long time, using AI felt simple: write a prompt, get an answer, and move on. This worked well for quick summaries, basic explanations, email drafts, and simple content generation. But as AI started being used for real business work, research, coding, decision-making, and automation, one thing became clear: real work does not happen in one perfect attempt.</p><p>Human work is naturally iterative. We draft, review, correct, improve, and refine. Developers test code. Researchers verify sources. Teams review ideas before acting on them. Most meaningful work moves through cycles of feedback and improvement.</p><p>This is where single-shot prompting shows its limits. A prompt can tell AI what to do, but it does not always help AI check whether the output is complete, accurate, or useful. The first answer may be a good start, but for complex tasks, it should not always be the final result.</p><p>Looping changes this. Instead of asking AI to answer once, looping gives AI a process: generate, evaluate, revise, and improve. Feedback becomes part of the workflow, not something added later.</p><p>That is why looping matters now. AI is no longer just a chatbot that responds to questions. It is becoming part of business processes, software development, research, customer support, content creation, and data analysis. In these workflows, quality depends not only on the prompt, but on what happens after the first response.</p><p>Prompting starts the conversation, but looping turns that conversation into improvement.</p><p><strong>Prompting vs Looping: The Simple Difference</strong></p><p>Prompting is the way most people first use AI. You give one instruction, and the AI gives one response.</p><p>For example:</p><p>“Write a short product description for this phone.”</p><p>The AI produces an answer based on that single request. This works well for simple tasks where the expected output is straightforward.</p><p>In simple terms:</p><p><strong>Prompting = one instruction → one response</strong></p><p>Looping works differently. In looping, the AI does not stop after the first response. The first output is checked, improved, and refined through one or more cycles before the final result is produced.</p><p>For example, AI may first write a product description, then check if key features are missing, improve the tone, review the target audience, and create the final version.</p><p>In simple terms:</p><p><strong>Looping = generate → check → improve → repeat</strong></p><p>Prompting is like asking for a first draft. Looping is like asking for a draft, review, edit, and improved final version.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2Yf3OD4P9B_sEE4o4VmgCA.png" /></figure><p><strong>Why Looping Is the Missing Layer</strong></p><p>Most people think better AI results come from better prompts. They add more context, define the role, give examples, set the tone, and explain the expected format. This helps because a clear prompt can lead to a better first response.</p><p>But prompting mainly improves the instruction.</p><p>Looping improves the process.</p><p>That is the real difference.</p><p>When we rely only on prompting, we expect one instruction to produce a strong final answer. This may work for simple tasks, but real work usually needs review, testing, verification, and improvement. Reports need editing. Code needs debugging. Research needs fact-checking. Customer responses need tone review.</p><p>This is where looping becomes the missing layer.</p><p>Looping adds a process around the AI response. Instead of stopping after the first answer, the workflow continues through checking, improving, and repeating. The AI is not only asked to produce something; it is guided to refine the output.</p><p>A simple way to understand this is:</p><p><strong>Prompting = Better Instruction</strong></p><p><strong>Looping = Better Process</strong></p><p>This is why looping is more than using multiple prompts. It is a workflow design layer. It helps move AI output from a rough first version to a stronger final result.</p><p>For example, if AI writes a project update, prompting can define the topic, tone, and format. But looping can check whether key points are missing, improve clarity, adjust the tone for leadership, and produce a polished version.</p><p>So the question changes from:</p><p>“Did I write the right prompt?”</p><p>to:</p><p>“Did I design the right process for AI to improve the result?”</p><p>Prompting starts the work, but looping shapes the work. The best AI workflows will not depend only on clever prompts. They will depend on well-designed loops that generate, check, improve, and repeat until the output is ready to use.</p><p><strong>How Looping Actually Works</strong></p><p>Looping may sound technical, but the basic idea is simple. It is a step-by-step process that helps AI move from a first draft to a stronger final output.</p><p>A simple AI loop looks like this:</p><p><strong>Draft → Evaluate → Revise → Validate → Final Output</strong></p><p>Each step has a purpose. In the <strong>Draft</strong> stage, AI creates the first version. In the <strong>Evaluate</strong> stage, the output is checked for gaps, accuracy, tone, and structure. In the <strong>Revise</strong> stage, AI improves the draft based on that review. In the <strong>Validate</strong> stage, the improved version is checked again to make sure it is ready to use.</p><p>For example, imagine AI is asked to write a business report. In a prompting-only approach, AI writes the report and stops. In a looping workflow, AI first creates a draft, checks whether sources or key points are missing, revises the report, verifies the facts, and then produces the final answer.</p><p>This is the power of looping. It does not treat the first answer as perfect. It treats the first answer as a starting point.</p><p>In simple terms, looping adds quality control to AI workflows. It helps turn a quick response into a more reliable result.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AdwDSvcGA92F3xV12X8eFQ.png" /></figure><p><strong>Common Looping Patterns in AI Workflows</strong></p><p>Looping does not always look the same. Different tasks need different types of loops. A writing task may need review and revision. A data task may need calculation and verification. A business process may need human approval before the final output is used.</p><p>The important point is that looping gives structure to improvement. It helps AI move through a task in a controlled way instead of producing one answer and stopping.</p><p>Here are some common looping patterns used in AI workflows.</p><p><strong>Generate–Review–Revise Loop</strong></p><p>This is one of the simplest and most useful looping patterns.</p><p>The AI first generates a draft. Then the draft is reviewed for quality, clarity, accuracy, tone, or completeness. After that, the AI revises the output based on the review.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YUCRJ16vp9smdfhIe_fEUw.png" /></figure><p>This pattern is useful for writing emails, blogs, reports, proposals, summaries, social posts, and presentations.</p><p>For example, an AI may write a blog introduction, review whether the hook is strong enough, revise the opening paragraph, and then produce a cleaner version. Instead of accepting the first draft, the workflow creates space for improvement.</p><p>This loop is powerful because most writing does not become strong in the first attempt. Good writing usually comes from drafting, reviewing, and rewriting.</p><p><strong>Tool-Use Loop</strong></p><p>In a tool-use loop, AI does not rely only on its first response. It uses tools to search, calculate, check data, retrieve information, or perform an action before continuing.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ocoguIrsHbVbP0TcbIwsyQ.png" /></figure><p>This pattern is useful when the task depends on current information, numbers, documents, databases, or external systems.</p><p>For example, an AI may be asked to prepare a market summary. Instead of guessing, it can search for recent data, check the numbers, compare sources, and then write the final summary. In another case, an AI may calculate totals from a spreadsheet, review the result, and then explain the findings.</p><p>The tool-use loop makes AI more useful because it connects the response to real information or real actions.</p><p><strong>Self-Correction Loop</strong></p><p>In a self-correction loop, the AI reviews its own answer and tries to find mistakes before giving the final response.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xMm_SLQf64pbM55_R6KHEA.png" /></figure><p>This pattern is useful when the first answer may have gaps, unclear reasoning, formatting issues, or missing details.</p><p>For example, after writing a customer support reply, the AI can review whether the message is polite, complete, and aligned with the customer’s issue. If it finds that the response is too cold or misses a key point, it can revise the answer before sharing it.</p><p>Self-correction does not make AI perfect, but it improves the chances of catching obvious mistakes before the output reaches the user.</p><p><strong>Human-in-the-Loop</strong></p><p>In a human-in-the-loop pattern, a person reviews or guides the AI before the final output is completed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ds4r-9Bo4l-QnAcvnJBr3Q.png" /></figure><p>This pattern is important when judgment, sensitivity, approval, or accountability matters.</p><p>For example, AI may create a first draft of a legal summary, HR communication, project update, or executive report. A human reviewer can then check the message, add context, correct assumptions, or approve the final version.</p><p>This loop combines the speed of AI with the judgment of a human. It is especially useful for high-impact work where the final decision should not be left fully to automation.</p><p><strong>Evaluation Loop</strong></p><p>In an evaluation loop, the AI output is tested against rules, scores, or quality checks before it is accepted.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zdRME5L4BZdwUbpPobqr8A.png" /></figure><p>This pattern is useful when the quality of the output needs to be measured in a structured way.</p><p>For example, a customer support answer can be checked against rules such as: Is the answer accurate? Is the tone professional? Did it answer the customer’s question? Did it avoid making unsupported promises? If the output does not pass the checks, it goes back for revision.</p><p>Evaluation loops are helpful because they make improvement more measurable. Instead of saying “make it better,” the workflow defines what “better” means.</p><p>Together, these looping patterns show that looping is not one fixed method. It is a flexible way to design AI workflows. The right loop depends on the task, the risk, the required quality, and the level of human involvement.</p><p>For simple tasks, a generate–review–revise loop may be enough. For data-heavy tasks, a tool-use loop may be better. For sensitive decisions, human-in-the-loop is often essential. For scalable systems, evaluation loops help maintain quality across many outputs.</p><p>The main idea is simple: AI becomes more reliable when its work is checked, improved, and guided through the right loop.</p><p><strong>Real-World Use Cases of Looping</strong></p><p>Looping becomes easier to understand when we look at where it is actually useful. In real work, AI is rarely used only to produce one quick answer. It is used to draft, check, improve, compare, verify, and finalize. That is why looping fits naturally into many everyday workflows.</p><p>Here are some real-world use cases where looping can make AI more practical and reliable.</p><p><strong>Blog Writing and Content Editing</strong></p><p>Content creation is one of the best examples of looping.</p><p>A writer may use AI to create a first draft, but the first draft is usually not the final version. It may need a stronger hook, clearer structure, better examples, simpler language, or a more natural tone.</p><p>A looping workflow for content may look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L4UPmGoB2TAjUVwHfPhOBg.png" /></figure><p>For example, AI can write a blog introduction, then review whether the opening is engaging, revise weak paragraphs, improve readability, and finally polish the content for publishing.</p><p>This makes AI more useful as a writing partner, not just a text generator.</p><p><strong>Software Coding and Debugging</strong></p><p>Coding is naturally iterative. Developers write code, test it, find errors, fix bugs, and test again. This makes looping very useful in software development.</p><p>A coding loop may look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*J-q_N9bZvj6wP4mmi4H3KA.png" /></figure><p>For example, AI can generate a function, review it for possible errors, suggest improvements, explain why the bug happened, and revise the code. If the code still fails, the loop continues until the issue is resolved.</p><p>This is more powerful than simply asking AI to “write code” once. The real value comes when AI helps with the full cycle of building, testing, debugging, and improving.</p><p><strong>Customer Support Workflows</strong></p><p>Customer support teams need responses that are accurate, helpful, polite, and consistent with company policy. A single AI-generated reply may not always meet all those requirements.</p><p>A customer support loop may look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GJ34CTm3t3JFW3PVsoMwKQ.png" /></figure><p>For example, AI can draft a response to a customer complaint, review whether it answers the actual problem, check if the tone is professional, ensure it does not promise something unsupported, and then produce a final response.</p><p>This helps teams respond faster while still maintaining quality and consistency.</p><p><strong>Document Review</strong></p><p>Many business documents need careful review before they are shared. This includes contracts, proposals, policies, reports, meeting notes, and presentations.</p><p>A document review loop may look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uUd3N2BYfLyjD_QlR9raQw.png" /></figure><p>For example, AI can review a proposal and check whether it has missing sections, unclear language, repeated points, inconsistent formatting, or weak arguments. After revision, the document can be checked again before it is finalized.</p><p>Looping is useful here because document quality often improves through multiple rounds of review.</p><p><strong>Data Analysis</strong></p><p>Data analysis is not only about generating charts or summaries. It also involves checking data quality, finding patterns, validating assumptions, and explaining results clearly.</p><p>A data analysis loop may look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-S6B-bQ-4h-mIKCSjvyriA.png" /></figure><p>For example, AI can summarize sales data, then check whether any numbers look unusual, compare trends across regions, identify missing data, and revise the final explanation to make it easier for business users to understand.</p><p>This makes AI more useful for decision-making because the output is not just a quick observation. It becomes a reviewed and refined insight.</p><p>These examples show why looping matters in the real world. The goal is not just to make AI answer faster. The goal is to make AI work better through repeated checking and improvement.</p><p>In simple tasks, one prompt may be enough. But in practical work, quality usually comes from a process. Looping gives AI that process.</p><p><strong>Why Looping Makes AI Better</strong></p><p>Looping makes AI better because it gives the system a chance to improve. A single prompt usually gives a first answer, but that answer may have gaps, unclear reasoning, missing details, or weak structure. Looping treats the first answer as a draft, not the final result.</p><p>That is why looping is powerful: it gives AI a second chance, and sometimes a third.</p><p>Looping improves <strong>accuracy</strong> because the output can be checked for missing facts, unclear claims, or unsupported statements. It improves <strong>quality</strong> because the tone, structure, examples, and flow can be refined before the final version is shared.</p><p>It also reduces <strong>first-draft errors</strong>. Instead of accepting the first response immediately, the workflow asks: Is anything missing? Is anything unclear? Is anything incorrect? Can this be improved?</p><p>Looping also makes AI outputs more <strong>reliable</strong>. The AI does not simply respond and stop. It follows a process: create, check, improve, validate, and finalize.</p><p>This is especially useful for complex tasks like writing reports, debugging code, analyzing data, reviewing documents, or preparing customer responses. These tasks need structure, checking, and improvement.</p><p>In simple terms:</p><p><em>Prompting gives AI a task.</em></p><p><em>Looping gives AI a path to a better result.</em></p><p><strong>Where Looping Can Go Wrong</strong></p><p>Looping can make AI workflows stronger, but it is not a magic fix. Like any good process, it needs direction. If a loop is poorly designed, it can waste time, repeat the same mistakes, or make an output look better without actually making it more reliable.</p><p>The biggest mistake is thinking that more steps always mean better results. They do not. A loop is useful only when each step has a clear purpose.</p><p>One risk is <strong>more time and cost</strong>. A single prompt gives one answer quickly, but a loop may involve several rounds of checking, revising, and validating. For simple tasks, that may be unnecessary. If you only need a quick sentence rewrite or a short summary, one prompt may be enough. Looping makes more sense when quality, accuracy, or reliability really matter.</p><p>Another risk is the <strong>endless loop</strong>. If there is no stopping rule, AI may keep revising without making the output meaningfully better. It may change words, adjust structure, or repeat checks even when the answer is already good enough. A good loop should know when to stop, such as after a fixed number of rounds, when all quality checks are passed, or when a human approves the result.</p><p>Looping can also fail when AI <strong>repeats the same mistake</strong>. For example, if a report includes an unsupported claim, the AI may rewrite the sentence but still keep the same weak claim. The output may sound better, but the real problem remains. This is why the checking step must focus on substance, not just style.</p><p>Weak evaluation is another problem. If the AI is only asked to “check if this is good,” the answer may create false confidence. A better loop asks specific questions: Are the facts correct? Is anything missing? Does the tone fit the audience? Are there any risks or assumptions? Clear checks lead to better results.</p><p>Finally, too much automation without human review can be risky. For sensitive work, such as legal content, financial decisions, HR communication, compliance, customer escalations, or executive updates, AI should support human judgment, not replace it.</p><p>The right balance is simple: use looping where it adds real value, set clear limits, check the output properly, and involve people when the stakes are high.</p><p>Looping works best when it is intentional. The goal is not to make AI repeat forever. The goal is to give AI enough chances to improve while still knowing when the result is ready.</p><p><strong>Best Practices for Building Loops</strong></p><p>Looping works best when it is designed with intention. A good loop is not just repeating prompts; it is a clear process that helps AI move from a first attempt to a better final result.</p><p>First, define what “good output” means. If the goal is unclear, the loop will also be unclear. For a blog, good output may mean a clear introduction, strong structure, simple language, useful examples, and no missing sections. For customer support, it may mean a polite, accurate response that follows company policy.</p><p>Second, set a limit. Every loop needs a maximum number of rounds. Without a limit, AI may keep revising even when the output is already good enough. A loop should improve the result, not continue forever.</p><p>Third, use external checks when possible. AI can review its own work, but tools, data sources, documents, tests, rules, or human feedback can make the loop stronger. These checks reduce guesswork and make the final output more reliable.</p><p>Fourth, keep humans involved for important decisions. For legal, financial, HR, medical, compliance, customer escalation, or executive-level work, AI should support human judgment, not replace it.</p><p>Fifth, measure improvement, not just activity. A loop is only useful if the output is actually getting better. Ask whether the answer is more accurate, clearer, more complete, and closer to the goal.</p><p>Finally, stop the loop when quality stops improving. Once the output meets the standard, no major issues remain, or a human approves it, the loop should end.</p><p>A simple loop may look like this:</p><p><strong>Goal → Draft → Check → Improve → Validate → Stop or Repeat</strong></p><p>The best loops are clear, measurable, and controlled. They focus on improvement, not repetition.</p><p><strong>The Future: From Prompt Engineering to Loop Engineering</strong></p><p>For the last few years, AI conversations have focused heavily on prompt engineering: writing better instructions, adding context, defining roles, and guiding AI toward better answers.</p><p>That will still matter, but the future of AI will not be defined only by better prompts. It will be defined by better systems around AI.</p><p>As AI becomes part of real workflows, the question is changing from:</p><p>“How do we ask AI better questions?”</p><p>to:</p><p>“How do we design better processes for AI to complete complex tasks?”</p><p>This is where loop engineering becomes important.</p><p>Loop engineering means designing the improvement cycle around AI. It includes prompts, tools, memory, evaluation, feedback, revision, and clear stopping points.</p><p>In simple terms:</p><p><strong>Prompt Engineering = Better Instructions</strong></p><p><strong>Loop Engineering = Better AI Workflows</strong></p><p>A strong AI workflow may look like this:</p><p><strong>Prompt → AI Output → Tool Use → Evaluation → Feedback → Revision → Final Result</strong></p><p>This shift matters because real work involves decisions, checks, revisions, approvals, and outcomes. A single prompt may start the task, but a well-designed loop helps complete it with more reliability.</p><p>The next stage of AI adoption may move from prompt engineering to loop engineering.</p><p>Prompt engineering teaches us how to ask.</p><p>Loop engineering teaches us how to improve.</p><p><strong>Conclusion: The Best AI Does Not Stop at the First Answer</strong></p><p>AI started for many people as a simple question-and-answer tool. You wrote a prompt, received a response, and decided whether it was useful. That approach still works for quick tasks, but it is not enough for serious workflows where quality, accuracy, structure, and reliability matter.</p><p>Real work is not completed in one attempt. We draft, review, correct, improve, and finalize. The same principle applies to AI. The first answer can be helpful, but it should not always be treated as the final answer.</p><p>This is why looping matters.</p><p>Looping gives AI a process for improvement. It creates space for checking, revision, validation, feedback, and human judgment. It turns AI from a tool that simply responds into a system that can work through a task step by step.</p><p>Prompting is still important because every AI workflow begins with instruction. But prompting alone focuses mainly on the first response. Looping focuses on the final result.</p><p>That is the real shift.</p><p>The future of AI will not belong only to people who write better prompts. It will belong to people and teams who design better workflows around AI. These workflows will include loops, tools, memory, evaluation, feedback, and clear stopping rules.</p><p>The best AI systems will not be the ones that answer fastest. They will be the ones that can improve, check their work, and produce outputs that are reliable enough for real use.</p><p>So the final takeaway is simple:</p><p><em>Prompting asks AI to answer. Looping teaches AI to improve.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=af2130360c84" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[We Thought Microservices Would Fix Everything… We Were Wrong]]></title>
            <link>https://medium.com/@balmikprajapati53/we-thought-microservices-would-fix-everything-we-were-wrong-0c6c5be01f33?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/0c6c5be01f33</guid>
            <category><![CDATA[modular-monolith]]></category>
            <category><![CDATA[system-design-project]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[backend-development]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Tue, 17 Mar 2026 17:17:50 GMT</pubDate>
            <atom:updated>2026-03-17T17:17:50.076Z</atom:updated>
            <content:encoded><![CDATA[<h3><strong>Why jumping to microservices too early can create more problems than it solves — and what to do instead.</strong></h3><h3><strong>Introduction</strong></h3><p>In many engineering environments, monolithic applications gradually become a drag on delivery and reliability. As systems grow, tight coupling, long build cycles, and coarse-grained scaling begin to slow teams down.</p><p>Deployments become heavier, cross-team coordination increases, and even small changes carry a higher risk of unintended side effects. Over time, the system becomes harder to evolve, not because of poor implementation, but because of accumulated complexity.</p><p>The natural response in such situations is to consider microservices. They promise independent deployments, better scalability, and improved team autonomy. On the surface, this seems like the logical next step.</p><p>However, in practice, this transition is not always as straightforward — or as beneficial — as it appears. In many cases, the real issue is not the architecture itself, but how the system is structured and maintained.</p><p>This raises a critical question:<br> <em>Should every growing monolith really be broken into microservices?</em></p><h3><strong>The Breaking Point</strong></h3><p>As the system continued to grow, the limitations of the monolithic architecture became increasingly visible — not because the design was fundamentally flawed, but because it was no longer aligned with the scale and pace of change.</p><p>One of the first signs was tight coupling across modules. Business logic that should have been isolated started leaking across boundaries, making even small changes risky. A modification in one area often requires careful validation across multiple parts of the system.</p><p>Over time, build and deployment cycles became heavier. What was once a quick and predictable process turned into a coordinated effort. Even minor updates required rebuilding and redeploying the entire application, increasing both time and risk.</p><p>Debugging also became significantly more complex. Identifying the root cause of an issue often involves tracing through multiple layers of intertwined logic. The lack of clear boundaries made it difficult to isolate failures, slowing down both development and incident resolution.</p><p>Scaling presented another major challenge. The system could only be scaled as a whole, even when performance bottlenecks were limited to specific components. This led to inefficient resource usage and increased infrastructure costs.</p><p>As team size and feature demands grew, coordination overhead increased as well. Multiple developers working on different parts of the system often had to navigate shared code paths, leading to conflicts, delays, and reduced development velocity.</p><p>Individually, these issues were manageable. But together, they created a clear signal:</p><p><em>The architecture that once enabled rapid development was now limiting it.</em></p><h3><strong>The Assumption: Microservices Will Fix It</strong></h3><p>Faced with growing complexity and slowing delivery, the idea of moving to microservices often emerges as the most logical solution. The promise is compelling: smaller, independent services, faster deployments, better scalability, and improved team autonomy.</p><p>At a high level, this shift appears to directly address many of the challenges seen in monolithic systems. If tightly coupled components are the problem, breaking them into independent services seems like the obvious answer.</p><p>However, this assumption overlooks an important reality:</p><p><em>Microservices do not eliminate complexity — they redistribute it.</em></p><p>Instead of managing complexity within a single codebase, it is spread across multiple services, each with its own lifecycle, deployment pipeline, and operational concerns. What was once an in-process function call becomes a network call, introducing latency, failure scenarios, and the need for resilience patterns.</p><p>Data management also becomes more challenging. Transactions that were previously simple and atomic now require coordination across services, often leading to eventual consistency models and additional design considerations.</p><p>Operational overhead increases significantly as well. Monitoring, logging, service discovery, fault tolerance, and deployment orchestration all become essential components of the system. Without strong infrastructure and processes in place, these can quickly become bottlenecks.</p><p>In many cases, teams realize that while microservices solve certain problems, they introduce a new set of challenges that must be carefully managed.</p><p>This leads to a critical insight:</p><p><em>Moving to microservices without first addressing structural issues can amplify existing problems rather than solve them</em><strong><em>.</em></strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*33xz61dKMBJCLP5zWuHrsg.png" /></figure><h3><strong>The Turning Point: Rethinking the Solution</strong></h3><p>Before committing to a full transition to microservices, it became necessary to step back and reassess the core problem.</p><p>The challenges were clear — tight coupling, difficult deployments, and limited scalability. But an important question emerged:</p><p><em>Were these issues caused by the monolithic architecture itself, or by how the system was structured internally?</em></p><p>This distinction proved critical.</p><p>Instead of immediately decomposing the system into distributed services, the focus shifted toward improving internal modularity. The goal was to retain the simplicity of a single deployable unit while introducing clear boundaries within the application.</p><p>This approach is commonly referred to as a modular monolith.</p><p>At its core, a modular monolith organizes the system into well-defined, independent modules, each aligned with a specific business capability. These modules interact through explicit interfaces rather than direct internal dependencies, reducing coupling and improving maintainability.</p><p>To achieve this, principles from <a href="https://www.domainlanguage.com/ddd/">Domain-Driven Design</a> were applied to identify clear domain boundaries. Each module was treated as a self-contained unit with its own logic and responsibilities.</p><p>Additionally, architectural patterns like <a href="https://alistair.cockburn.us/hexagonal-architecture">Hexagonal Architecture</a> helped separate business logic from external concerns such as databases, APIs, and frameworks. This ensured that core logic remained stable and adaptable over time.</p><p>The impact of these changes was immediate and measurable:</p><ul><li>Code became easier to navigate and reason about</li><li>Changes were more predictable and localized</li><li>Deployment complexity remained low</li><li>Teams could work with greater independence</li></ul><p>Most importantly, many of the original problems — often attributed to the monolith — were significantly reduced without introducing the overhead of a distributed system.</p><p>This led to a key realization:</p><p><em>A well-structured monolith can deliver many of the benefits typically associated with microservices — without the added operational complexity.</em></p><p>Rather than replacing the architecture, the system had been evolved into a more maintainable and scalable form.</p><h3><strong>Real-World Examples: Who Is Actually Doing This?</strong></h3><p>The idea of a modular monolith is not just theoretical. Some of the most successful tech companies have followed this path — intentionally or as part of their evolution.</p><p><strong>Shopify</strong></p><ul><li>Scaled a monolithic architecture for years</li><li>Invested heavily in internal modularity</li><li>Delayed microservices until absolutely necessary</li></ul><p><strong>Insight:</strong> Scale doesn’t demand microservices — good design does.</p><p><strong>GitHub</strong></p><ul><li>Built on a large Rails monolith</li><li>Focused on clear boundaries and maintainability</li><li>Gradually extracted services only where needed</li></ul><p><strong>Insight:</strong> Even at a massive scale, monoliths can work when structured well.</p><p><strong>Amazon</strong></p><ul><li>Now a microservices leader</li><li>But transitioned gradually over time</li><li>Broke systems down based on real scaling pressure</li></ul><p><strong>Insight:</strong> Microservices are an evolution — not a starting point.</p><p><strong>Netflix</strong></p><ul><li>Adopted microservices due to extreme scale needs</li><li>Built a strong infrastructure before fully committing</li></ul><p><strong>Insight:</strong> Microservices succeed only with operational maturity.</p><p><strong>The Pattern Is Clear</strong></p><p>They didn’t start with microservices.<br> They earned the need for them.</p><h3><strong>The Reality Check: Choosing What Actually Fits</strong></h3><p>At this point, the question is no longer <em>“monolith vs microservices?”</em> but rather:</p><p><em>Which approach makes sense for the current stage of the system and the team?</em></p><p>A modular monolith and microservices are not competing ideas — they solve similar problems at different levels of scale and complexity.</p><p>A modular monolith focuses on improving structure within a single application. It introduces clear boundaries, reduces coupling, and keeps deployment simple. For many teams, this is enough to restore development speed and maintainability without adding operational overhead.</p><p>Microservices, on the other hand, extend this idea further by physically separating those modules into independent services. This enables independent deployments and fine-grained scaling, but also introduces the challenges of distributed systems.</p><p>In practice, the difference often comes down to trade-offs.</p><p>With a modular monolith, you benefit from simplicity:</p><ul><li>One codebase</li><li>One deployment pipeline</li><li>Easier debugging and testing</li></ul><p>But you are still limited in terms of:</p><ul><li>Independent scaling</li><li>Full team autonomy at a very large scale</li></ul><p>With microservices, you gain flexibility:</p><ul><li>Services can scale independently</li><li>Teams can deploy without coordination</li><li>Failures can be isolated</li></ul><p>However, this comes at the cost of:</p><ul><li>Increased infrastructure complexity</li><li>Network communication overhead</li><li>More complex data consistency models</li></ul><p>The key is to recognize that microservices are not an upgrade — they are a shift in complexity.</p><p>For small to mid-sized teams, or systems that are still evolving, a modular monolith often provides the best balance between structure and simplicity.</p><p>As systems grow — both in terms of traffic and organizational scale — microservices can become a natural next step, especially when certain parts of the system demand independent scaling or faster release cycles.</p><p>This leads to a practical way of thinking about the decision:</p><p><em>Start with simplicity. Introduce complexity only when it is justified.</em></p><h3><strong>The Migration Journey: Evolving with the Strangler Pattern</strong></h3><p>Once the system was stabilized as a modular monolith, the next step was not an immediate shift to microservices — but a controlled and incremental evolution.</p><p>A complete rewrite was never considered a viable option. It introduces high risk, long timelines, and uncertainty in production systems. Instead, the approach focused on gradually extracting parts of the system where it made the most sense.</p><p>This is where the<br> <a href="https://microservices.io/patterns/refactoring/strangler-application.html,https:/martinfowler.com/bliki/StranglerFigApplication.html">Strangler Fig Pattern</a><br> became highly effective.</p><p>The idea is simple:<br> <em>Instead of replacing the entire system at once, you gradually “strangle” the monolith by building new services around it and slowly redirecting traffic</em><strong><em>.</em></strong></p><p><strong>Step 1: Identify the Right Candidates</strong></p><p>Not every module should be extracted immediately.</p><p>The focus was on:</p><ul><li>Components with high traffic or scaling needs</li><li>Modules with frequent changes</li><li>Clearly defined business boundaries</li></ul><p>This ensured that the effort delivered real value early.</p><p><strong>Step 2: Introduce an API Layer</strong></p><p>An API layer (or gateway) was introduced to act as a single entry point.</p><p>Instead of clients calling the monolith directly:</p><ul><li>Requests were routed through the API layer</li><li>This allowed selective redirection to new services</li></ul><p>This step is critical for controlling the migration.</p><p><strong>Step 3: Extract the First Service</strong></p><p>A single module was isolated and developed as an independent service:</p><ul><li>Its logic was removed from the monolith</li><li>A dedicated database or schema was introduced (where feasible)</li><li>Communication was handled via APIs</li></ul><p>Traffic for that specific functionality was then routed to the new service.</p><p><strong>Step 4: Gradual Traffic Shift</strong></p><p>Rather than switching everything at once:</p><ul><li>Traffic was moved incrementally</li><li>The system was monitored closely</li><li>Rollbacks were kept simple</li></ul><p>This reduced risk and ensured stability.</p><p><strong>Step 5: Repeat the Process</strong></p><p>The same approach was applied iteratively:</p><ul><li>Identify the next candidate</li><li>Extract</li><li>Route traffic</li><li>Monitor</li></ul><p>Over time, the system naturally evolved into a set of services where it actually made sense.</p><p><strong>A Critical Consideration: Data Management</strong></p><p>One of the most challenging aspects of this transition was handling data.</p><p>As services were extracted:</p><ul><li>Shared database access had to be reduced</li><li>Clear ownership of data was established</li><li>In some cases, event-driven communication was introduced</li></ul><p>This helped maintain consistency without tight coupling.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*JKbPKUbY4cAksyurmkt8OA.png" /></figure><h3><strong>The Challenges: The Hard Truths About Microservices</strong></h3><p>Microservices are often presented as the ideal solution to scaling and maintainability problems.<br> But in reality, they introduce a completely new set of challenges — many of which are significantly harder than those in a monolith.</p><p>Understanding these challenges is critical before deciding to adopt them.</p><p><strong>Data Consistency Is No Longer Simple</strong></p><p>In a monolith, maintaining data consistency is straightforward.<br> A single database and transactional boundaries ensure everything stays in sync.</p><p>With microservices:</p><ul><li>Each service often owns its own database</li><li>Transactions span across services</li><li>Strong consistency becomes difficult</li></ul><p>This leads to:</p><ul><li>Eventual consistency models</li><li>Increased complexity in handling failures</li><li>Need for patterns like Saga or event-driven communication</li></ul><p><em>What was once a simple transaction becomes a distributed coordination problem.</em></p><p><strong>Debugging Becomes Distributed<br> </strong>Debugging in a monolith usually involves tracing a single codebase.</p><p>In microservices:</p><ul><li>A single request may pass through multiple services</li><li>Logs are scattered across systems</li><li>Failures may occur due to network latency, timeouts, or partial outages</li></ul><p>To handle this, teams need:</p><ul><li>Centralized logging</li><li>Distributed tracing</li><li>Correlation IDs</li></ul><p><em>Finding the root cause is no longer straightforward — it requires system-wide visibility.</em></p><p><strong>Deployment Complexity Increases</strong></p><p>In a monolith:</p><ul><li>One build</li><li>One deployment</li><li>One release cycle</li></ul><p>In microservices:</p><ul><li>Multiple services with independent deployments</li><li>Version compatibility between services</li><li>CI/CD pipelines for each component</li></ul><p>This introduces:</p><ul><li>Deployment coordination challenges</li><li>Risk of breaking inter-service communication</li><li>Need for strong automation and release strategies</li></ul><p><em>Faster deployments are possible — but only with mature processes.</em></p><p><strong>Monitoring Is Not Optional — It’s Critical</strong></p><p>With distributed systems, observability becomes essential.</p><p>Teams must monitor:</p><ul><li>Service health</li><li>Latency between services</li><li>Error rates</li><li>Infrastructure performance</li></ul><p>This requires investment in:</p><ul><li>Metrics collection</li><li>Alerting systems</li><li>Real-time dashboards</li></ul><p><em>Without proper monitoring, failures can go unnoticed until they impact users.</em></p><p><strong>The Reality</strong></p><p><strong><em>Microservices don’t reduce complexity — they redistribute it.</em></strong></p><p>They shift complexity from code structure (monolith) to:</p><ul><li>Network communication</li><li>Data consistency</li><li>Infrastructure and operations</li></ul><h3><strong>Tools &amp; Tech: A Java Perspective</strong></h3><p>While architecture decisions matter the most, the right tools can make implementation significantly smoother.</p><p>From a Java ecosystem perspective, a few technologies consistently stand out when working with modular monoliths and microservices.<br> <br> <strong>Spring Boot</strong></p><p>The backbone of most modern Java applications.</p><ul><li>Simplifies building production-ready applications</li><li>Works well for both monoliths and microservices</li><li>Strong ecosystem for REST APIs, security, and data access</li></ul><p>Whether starting with a modular monolith or moving to microservices, it provides a solid foundation<strong>.</strong></p><p><strong>Docker</strong></p><p>Makes applications portable and consistent across environments.</p><ul><li>Packages applications with all dependencies</li><li>Eliminates “works on my machine” issues</li><li>Essential for running services independently</li></ul><p>A key step toward preparing your system for distributed architecture.</p><p><strong>Kubernetes</strong></p><p>Handles orchestration at scale.</p><ul><li>Manages container deployment and scaling</li><li>Provides self-healing and load balancing</li><li>Enables efficient resource utilization</li></ul><p>Particularly useful once the system grows beyond a few services.</p><p><strong>Final Thought</strong></p><p>Tools don’t define architecture — but they enable it.</p><p>The real value comes from:</p><ul><li>Clear boundaries</li><li>Thoughtful design</li><li>Incremental evolution</li></ul><p>The tools simply help execute that vision effectively.</p><h3><strong>Key Lessons Learned</strong></h3><p>Looking back, the journey wasn’t just about changing architecture — it was about changing how we think about systems.</p><p>A few lessons stood out clearly:</p><ul><li>Don’t jump to microservices too early<br> What looks like a scalability problem is often a design problem.</li><li>Good design matters more than fancy architecture<br> Clear boundaries and modular thinking solve most issues before scale even becomes a concern.</li><li>Start simple, then evolve intentionally<br> Complexity should be introduced only when there’s a real need — not as a default choice.</li><li>A modular monolith is not a compromise<br> It’s often the most practical and efficient architecture for a large range of systems.</li><li>Microservices require organizational maturity<br> Without strong DevOps practices, monitoring, and ownership, they can create more problems than they solve.</li></ul><h3><strong>What I’d Do Today (With Experience)</strong></h3><p>If I were starting a system today, knowing everything I’ve learned, my approach would be very different.</p><p>I would:</p><ul><li>Start with a well-structured modular monolith<br> Focus on domain boundaries, not distribution.</li><li>Apply principles like Domain-Driven Design from the beginning<br> This makes future transitions significantly easier.</li><li>Design for change, not for scale on day one<br> Most systems don’t fail because they can’t scale — they fail because they’re hard to change.</li><li>Introduce microservices only when there is clear pressure<br> Such as independent scaling needs, team ownership, or deployment bottlenecks.</li></ul><p>Invest early in observability and automation<br> These become critical long before microservices enter the picture.</p><h3><strong>Final Thought</strong></h3><p><em>Architecture is not about trends.<br> It’s about solving the problem you actually have.</em></p><p>Start simple.<br> Design well.<br> Evolve when necessary.</p><p>Because in the end — <br> <strong>The best architecture is the one your team can actually manage.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0c6c5be01f33" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Solving Circular Dependency Issues in Spring Boot using @Lazy and Service Decomposition]]></title>
            <link>https://medium.com/@balmikprajapati53/solving-circular-dependency-issues-in-spring-boot-using-lazy-and-service-decomposition-15f372cdaaee?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/15f372cdaaee</guid>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Tue, 11 Mar 2025 16:17:38 GMT</pubDate>
            <atom:updated>2025-03-19T14:52:09.341Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Introduction:</strong></p><p>Circular dependencies in Spring Boot applications can lead to frustrating startup issues and errors, making it a challenge to maintain clean and scalable code. These errors occur when two or more beans depend on each other, causing Spring’s Dependency Injection to fail. While Spring provides various strategies to handle circular dependencies, such as constructor injection and setter injection, the <strong>@Lazy</strong> annotation, combined with service decomposition, can be a powerful solution to break the cycle.</p><p>This blog will walk you through a practical solution using <strong>@Lazy</strong> to resolve circular dependency issues, breaking down larger services into smaller, more manageable pieces. This approach not only helps resolve circular dependencies but also improves the maintainability and scalability of your Spring Boot application.</p><h3>The Circular Dependency Problem</h3><p>Circular dependencies typically occur when two or more beans rely on each other directly or indirectly. In such cases, Spring’s bean initialization mechanism gets stuck because it can’t decide which bean to initialize first.</p><p>For example, consider the following scenario:</p><ul><li>ServiceA has a dependency on ServiceB</li><li>ServiceB has a dependency on ServiceA</li></ul><p>This interdependence creates a circular reference and prevents Spring from creating the beans. If you try to run the application, you will encounter an error like:</p><pre>org.springframework.beans.factory.UnsatisfiedDependencyException: <br>Error creating bean with name &#39;ServiceA&#39;: <br>Unsatisfied dependency expressed through field &#39;serviceB&#39;.</pre><h3>Solution: Breaking the Circular Dependency</h3><p>One effective way to resolve circular dependencies in Spring Boot is by <strong>using the </strong><strong>@Lazy annotation</strong>. This solution allows Spring to initialize beans lazily, meaning the bean will be created only when it’s actually needed, thereby breaking the circular reference.</p><p>Additionally, <strong>splitting large services into smaller, independent services</strong> is an excellent practice. Instead of having one service depend on another directly, we can break them down and make each service more independent.</p><h4>Steps to Resolve Circular Dependency using @Lazy:</h4><ul><li><strong>Identify the circular dependency</strong>: Start by analyzing your code to identify where circular dependencies are happening. In most cases, this is caused by complex services that are tightly coupled.</li><li><strong>Decompose services</strong>: Break down large services into smaller components. This increases modularity and reduces interdependencies.</li><li><strong>Apply </strong><strong>@Lazy annotation</strong>: You can apply the @Lazy annotation to any of the beans that are involved in the circular dependency. This will delay the creation of the bean until it is actually required.</li></ul><pre>@Service<br>public class ServiceA {<br>    @Autowired<br>    @Lazy<br>    private ServiceB serviceB; // Lazy load ServiceB to avoid circular dependency<br>}<br><br>@Service<br>public class ServiceB {<br>    @Autowired<br>    @Lazy<br>    private ServiceA serviceA; // Lazy load ServiceA to avoid circular dependency<br>}</pre><p><strong>. Test the solution</strong>: Once you have applied the @Lazy annotation, you can test the application to ensure that the circular dependency is resolved, and beans are being initialized properly without errors.</p><h3>Breaking Large Services into Smaller Services</h3><p>Circular dependencies often arise in large, monolithic services where each component relies on others for most of the functionality. A good practice is to refactor the application by breaking these large services into smaller, more manageable pieces.</p><ul><li><strong>Service Decomposition</strong>: Divide each service into multiple smaller services that handle specific tasks. This reduces the interdependencies between beans and leads to a cleaner, more modular design.</li><li><strong>Interface-based Design</strong>: Instead of direct dependencies between services, consider using interfaces or service abstractions. This helps decouple the components and allows for easier unit testing and flexibility in service replacement.</li></ul><h3>Pros and Cons of Using @Lazy to Resolve Circular Dependencies</h3><h4>Pros:</h4><ul><li><strong>Quick Resolution</strong>: The @Lazy annotation is an immediate and effective solution to circular dependency issues.</li><li><strong>Improved Performance</strong>: By deferring the creation of beans, you can optimize startup time, especially if some beans are not immediately required.</li><li><strong>Flexible Design</strong>: Using lazy initialization can give your code a more flexible and modular design, making it easier to maintain.</li></ul><h4>Cons:</h4><ul><li><strong>Potential Hidden Errors</strong>: The use of @Lazy can sometimes hide underlying design issues, making the application appear to work even if there are deeper architectural problems.</li><li><strong>Delayed Dependencies</strong>: While lazy loading can be helpful, it also means that dependencies will not be available until they are explicitly used, which can lead to unexpected behavior if not managed properly.</li><li><strong>Increased Complexity</strong>: If overused, lazy loading can introduce unnecessary complexity in your application, making it harder to track the order in which beans are created and initialized.</li></ul><h3>Conclusion</h3><p>Circular dependencies are a common challenge in Spring Boot applications, but with careful design and the strategic use of the @Lazy annotation, you can avoid these pitfalls. Breaking down larger services into smaller components is a best practice that can lead to cleaner, more maintainable code.</p><p>Remember, while @Lazy can resolve immediate circular dependency issues, it’s important to also consider service decomposition and modular design to ensure long-term maintainability and scalability of your application.</p><p>By following these strategies, you can not only solve circular dependency problems but also create a robust and scalable Spring Boot application architecture.</p><h3>Final Thoughts</h3><p>Dealing with circular dependencies doesn’t have to be a painful process. Whether you’re using @Lazy or restructuring your services, the key is to break down large, tightly coupled components into smaller, more independent ones. This will make your code more modular and flexible, allowing it to grow and evolve without unnecessary roadblocks.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=15f372cdaaee" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Mastering ActiveMQ Integration with Spring Boot 3.3.x on JDK 17+: A Step-by-Step Guide]]></title>
            <link>https://medium.com/@balmikprajapati53/integration-of-activemq-with-spring-boot-3-3-x-on-jdk-17-a-complete-guide-32fd2281df9d?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/32fd2281df9d</guid>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Wed, 11 Dec 2024 10:20:23 GMT</pubDate>
            <atom:updated>2024-12-11T10:28:59.046Z</atom:updated>
            <content:encoded><![CDATA[<p>ActiveMQ is a popular open-source message broker that facilitates asynchronous communication between systems. In this guide, we’ll demonstrate how to integrate ActiveMQ with Spring Boot 3.3.x while using JDK 17+. By the end of this tutorial, you will have a fully functional application that sends and receives messages via ActiveMQ.</p><h3>Prerequisites</h3><ul><li><strong>JDK 17 or higher</strong> installed on your machine.</li><li><strong>Spring Boot 3.3.x</strong> (3.3.5 in this tutorial).</li><li>Basic knowledge of Java and Spring Boot.</li><li>Maven for managing dependencies.</li></ul><h3>Step 1: Project Setup</h3><h3>pom.xml</h3><p>Here is the Maven pom.xml file to set up your Spring Boot application:</p><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;<br>&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot;<br>	xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;<br>	xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;<br>	&lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;<br>	&lt;groupId&gt;com.techprimers.messaging&lt;/groupId&gt;<br>	&lt;artifactId&gt;spring-boot-latest-version-activemq&lt;/artifactId&gt;<br>	&lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;<br>	&lt;packaging&gt;jar&lt;/packaging&gt;<br>	&lt;name&gt;spring-boot-latest-version-activemq&lt;/name&gt;<br>	&lt;description&gt;Demo project for Spring Boot&lt;/description&gt;<br>	&lt;parent&gt;<br>		&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>		&lt;artifactId&gt;spring-boot-starter-parent&lt;/artifactId&gt;<br>		&lt;version&gt;3.3.5&lt;/version&gt;<br>		&lt;relativePath /&gt; &lt;!-- lookup parent from repository --&gt;<br>	&lt;/parent&gt;<br>	&lt;properties&gt;<br>		&lt;java.version&gt;17&lt;/java.version&gt;<br>	&lt;/properties&gt;<br>	&lt;dependencies&gt;<br>		&lt;dependency&gt;<br>			&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>			&lt;artifactId&gt;spring-boot-starter-activemq&lt;/artifactId&gt;<br>		&lt;/dependency&gt;<br>		&lt;dependency&gt;<br>			&lt;groupId&gt;org.apache.activemq&lt;/groupId&gt;<br>			&lt;artifactId&gt;activemq-broker&lt;/artifactId&gt;<br>		&lt;/dependency&gt;<br>		&lt;dependency&gt;<br>			&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>			&lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;<br>		&lt;/dependency&gt;<br>		&lt;dependency&gt;<br>			&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>			&lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;<br>			&lt;scope&gt;test&lt;/scope&gt;<br>		&lt;/dependency&gt;<br>	&lt;/dependencies&gt;<br>	&lt;build&gt;<br>		&lt;plugins&gt;<br>			&lt;plugin&gt;<br>				&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>				&lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;<br>			&lt;/plugin&gt;<br>		&lt;/plugins&gt;<br>	&lt;/build&gt;<br>&lt;/project&gt;</pre><h3>Step 2: Configure Application Properties</h3><p>Add the following configurations in the application.properties file to enable an embedded ActiveMQ broker:</p><pre># Enable ActiveMQ embedded broker<br>spring.activemq.broker-url=vm://localhost?broker.persistent=false<br>spring.activemq.in-memory=true<br>spring.activemq.packages.trust-all=true<br><br>server.port=8081</pre><p>This configuration sets up an in-memory ActiveMQ broker and specifies the server port as 8081.</p><h3>Step 3: Main Application Class</h3><p>Create the main Spring Boot application class ActiveMqDemoApplication.java:</p><pre>package com.example.activemqdemo;<br><br>import org.springframework.boot.SpringApplication;<br>import org.springframework.boot.autoconfigure.SpringBootApplication;<br>@SpringBootApplication<br>public class ActiveMqDemoApplication {<br>    public static void main(String[] args) {<br>        SpringApplication.run(ActiveMqDemoApplication.class, args);<br>    }<br>}</pre><h3>Step 4: Create JMS Configuration</h3><p>Create a JmsConfig.java file to configure the ActiveMQ connection:</p><pre>package com.example.activemqdemo.config;<br><br>import org.apache.activemq.ActiveMQConnectionFactory;<br>import org.springframework.context.annotation.Bean;<br>import org.springframework.context.annotation.Configuration;<br>import org.springframework.jms.annotation.EnableJms;<br>import org.springframework.jms.core.JmsTemplate;<br>@Configuration<br>@EnableJms<br>public class JmsConfig {<br>    @Bean<br>    public ActiveMQConnectionFactory activeMQConnectionFactory() {<br>        ActiveMQConnectionFactory connectionFactory = new ActiveMQConnectionFactory();<br>        connectionFactory.setBrokerURL(&quot;vm://localhost?broker.persistent=false&quot;);<br>        return connectionFactory;<br>    }<br>    @Bean<br>    public JmsTemplate jmsTemplate(ActiveMQConnectionFactory connectionFactory) {<br>        return new JmsTemplate(connectionFactory);<br>    }<br>}</pre><h3>Step 5: Implement Message Producer</h3><p>Create a MessageProducer.java class to send messages to the ActiveMQ queue:</p><pre>package com.example.activemqdemo.config;<br><br>import org.springframework.beans.factory.annotation.Autowired;<br>import org.springframework.jms.core.JmsTemplate;<br>import org.springframework.stereotype.Component;<br>@Component<br>public class MessageProducer {<br>    @Autowired<br>    private JmsTemplate jmsTemplate;<br>    private static final String QUEUE_NAME = &quot;testQueue&quot;;<br>    public void sendMessage(String message) {<br>        jmsTemplate.convertAndSend(QUEUE_NAME, message);<br>        System.out.println(&quot;Message sent: &quot; + message);<br>    }<br>}</pre><h3>Step 6: Implement Message Consumer</h3><p>Create a MessageConsumer.java class to listen for messages from the ActiveMQ queue:</p><pre>package com.example.activemqdemo.config;<br><br>import org.springframework.jms.annotation.JmsListener;<br>import org.springframework.stereotype.Component;<br>@Component<br>public class MessageConsumer {<br>    @JmsListener(destination = &quot;testQueue&quot;)<br>    public void receiveMessage(String message) {<br>        System.out.println(&quot;Received message: &quot; + message);<br>    }<br>}</pre><h3>Step 7: Create REST Controller</h3><p>Create a MessageController.java class to expose an endpoint for sending messages:</p><pre>package com.example.activemqdemo.controller;<br><br>import com.example.activemqdemo.config.MessageProducer;<br>import org.springframework.beans.factory.annotation.Autowired;<br>import org.springframework.web.bind.annotation.GetMapping;<br>import org.springframework.web.bind.annotation.RequestMapping;<br>import org.springframework.web.bind.annotation.RestController;<br>@RestController<br>@RequestMapping(&quot;/rest/publish&quot;)<br>public class MessageController {<br>    @Autowired<br>    private MessageProducer messageProducer;<br>    @GetMapping(&quot;/send&quot;)<br>    public String sendMessage() {<br>        String message = &quot;Hello from ActiveMQ!&quot;;<br>        messageProducer.sendMessage(message);<br>        return &quot;Message sent to ActiveMQ: &quot; + message;<br>    }<br>}</pre><h3>Testing the Application</h3><ol><li>Run the Spring Boot application using your IDE or mvn spring-boot:run.</li><li>Access the REST endpoint to send a message:</li></ol><pre>http://localhost:8081/rest/publish/send</pre><p>3. Check the console logs to see the producer’s sent message and the consumer’s received message:</p><pre>Message sent: Hello from ActiveMQ!<br>Received message: Hello from ActiveMQ!</pre><h3>Conclusion</h3><p>In this tutorial, we successfully integrated ActiveMQ with Spring Boot 3.3.x on JDK 17+. We configured an embedded ActiveMQ broker, implemented a producer and consumer, and exposed a REST endpoint for sending messages.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=32fd2281df9d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Future of APIs: How GraphQL Is Evolving the Landscape.]]></title>
            <link>https://medium.com/@balmikprajapati53/the-future-of-apis-how-graphql-is-evolving-the-landscape-9e9a67c376c7?source=rss-681587818157------2</link>
            <guid isPermaLink="false">https://medium.com/p/9e9a67c376c7</guid>
            <dc:creator><![CDATA[Balmik Prajapati ]]></dc:creator>
            <pubDate>Thu, 25 Jan 2024 06:43:42 GMT</pubDate>
            <atom:updated>2024-01-25T08:53:52.397Z</atom:updated>
            <content:encoded><![CDATA[<p>In contemporary software development, the utilization of diverse architectural paradigms and communication technologies is instrumental in the creation of systems that are both scalable and flexible. A prevalent architectural technique known as micro services involves the decomposition of large programs into smaller, autonomous services. These services effectively communicate with one another through the utilization of APIs, with the REST API standard being particularly favored due to its simplicity and statelessness. Conversely, Facebook’s GraphQL provides an optimized approach by enabling users to precisely request the specific data they require. Additionally, gRPC, Google’s framework for remote procedure calls, facilitates efficient communication between micro services through the utilization of Protocol Buffers and HTTP/2. With a robust toolkit at their disposal, developers are empowered to design and develop distributed systems that are highly adaptable, resilient, and scalable.</p><h4><strong>Why GraphQL?</strong></h4><p>In web development, traditional RESTful APIs face challenges in meeting the diverse data retrieval needs of clients. The one-size-fits-all approach often leads to over-fetching or under-fetching of data, resulting in inefficient use of network resources and suboptimal application performance. Moreover, the cumbersome process of orchestrating multiple endpoints for distinct resources and dealing with versioning issues can hinder the agility of development teams.</p><p>To address these challenges, there is a need for a more flexible and efficient data querying solution that allows clients to request only the data they require, minimizing unnecessary data transfer and improving the overall user experience. Additionally, the solution should provide a robust mechanism for real-time data updates, strong typing, and a clear schema definition, ensuring effective communication between clients and servers.</p><h4><strong>GraphQL</strong></h4><p>GraphQL is a specialized query language and runtime designed for APIs in modern web development. Unlike traditional REST APIs, GraphQL provides a more tailored and efficient approach to data retrieval. Clients can precisely specify the data they require, leading to optimized network usage and enhanced application performance.</p><p>At its core, GraphQL operates as a runtime that executes queries against a predefined schema. This schema ensures strong typing, allowing for clear communication between clients and servers. A standout capability of GraphQL lies in its ability to facilitate real-time data updates using subscriptions. This empowers applications to deliver dynamic and interactive user experiences, keeping content and interactions up to date in real-time.</p><p>In essence, GraphQL serves as a developer-friendly tool, offering a single endpoint for accessing various resources. This fosters agility and adaptability in building applications, making it a valuable asset in the contemporary landscape of web development.</p><h4><strong>Data fetching with GraphQL vs Rest</strong></h4><p>I’m obtaining book details by id using the Rest API, as you can see in the picture below. I can get book data for the specific id in the response. However, if the user simply wants the book’s title and description, it becomes conceivable to modify the data structure accordingly. However, a user utilizing GraphQL only needs to submit a query at the time of request in order to obtain the book’s title and description via the same endpoint.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*LL7MatovKeocEC6D__uDVg.png" /></figure><p>In contrast, GraphQL only requires a single query to be sent to the GraphQL server along with the specific data required. The server then responds with a JSON object where these requirements are fulfilled. As you can see in the picture below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*aKpWiX3xrVArBtQmw3_q6w.png" /></figure><h4><strong>Data fetching with GraphQL vs gRPC</strong></h4><p>GraphQL and gRPC are two distinct technologies employed in the development of APIs, each serving diverse purposes, structures, and use cases. It is imperative to comprehend the unique characteristics of each before delving into practical examples illustrating the process of data fetching using GraphQL and gRPC. Let us delve into a brief exploration of both technologies, followed by illustrative examples to underscore their respective approaches to data retrieval.</p><p><strong>GraphQL</strong></p><p>GraphQL is a specific query language for APIs, and it is supported by a runtime that can perform these queries on data that already exists. Its main goal is to empower customers by giving them the ability to ask for the exact facts they need. With the GraphQL paradigm, clients actively define the response’s structure, and servers adapt to enable a powerful and adaptable method of manipulating and retrieving data. Generally, GraphQL requests are sent as HTTP POST requests to a specified endpoint, which is usually indicated by the notation /graphql. The efficiency and accuracy of data exchange between clients and servers are improved by this interaction approach.</p><p><strong>1.Adaptability in querying:</strong></p><p>GraphQL enables users to request just the precise data they require. In the example, the client can use a flexible query to retrieve user data and can define the fields that are needed.</p><p><strong>Example of Code:</strong></p><pre>query {users {id username email}}</pre><p><strong>2.Schema Readable by Humans:</strong></p><p>Most GraphQL schemas are self-documenting and readable by humans. The data’s structure is precisely defined by the schema, which facilitates comprehension and manipulation by developers.</p><p><strong>Example of Code (Schema):</strong></p><pre>type User {id: ID<br>username: String<br>email: String<br>age: Int}</pre><p><strong>3.Just One Endpoint</strong></p><p>By exposing a single endpoint for every query, GraphQL usually minimizes the amount of network requests. In a single query, clients can obtain all the information they require.</p><p><strong>Example Code for GraphQL Endpoint:</strong></p><pre>/grapghql</pre><p><strong>gRPC</strong></p><p>gRPC, or Remote Procedure Call, stands out as a high-performance and open-source framework designed to operate seamlessly in diverse environments. It is particularly favored for its ability to construct robust and scalable micro services that deliver efficiency in their execution.</p><p>At the core of gRPC is its utilization of protocol buffers (protobuf) as an interface definition language. This powerful mechanism enables the precise definition of service methods and message types. Additionally, gRPC exhibits versatility by providing support for multiple programming languages, allowing developers to implement solutions using the language of their preference. This structural flexibility contributes to gRPC’ s reputation as a reliable framework for building distributed systems with a focus on performance and interoperability<strong>.</strong></p><p><strong>1.Efficient Binary Protocol:</strong></p><p>gRPC uses Protocol Buffers, a binary serialization format, which can be more efficient in terms of payload size compared to JSON used in GraphQL. This can lead to better performance and reduced network overhead.</p><p><strong>Code Sample (Protocol Buffer):</strong></p><pre>message User {int32 id = 1;<br>string username = 2;<br>string email = 3;<br>int32 age = 4;}</pre><p><strong>2.Strong Typing:</strong></p><p>gRPC enforces strong typing through Protocol Buffers, which can help catch errors at compile-time. This can be beneficial for maintaining a more robust and reliable codebase.</p><p><strong>Code Sample (gRPC Service):</strong></p><pre>service UserService {rpc GetUsers (UserRequest)<br>returns UserResponse);}</pre><p><strong>3.Code Generation:</strong></p><p>gRPC generates client and server code based on the service definition, making it easier to integrate and maintain. This can help in avoiding manual implementation errors.</p><p><strong>Code Sample (gRPC Client):</strong></p><pre>UserResponse response = UserResponse.newBuilder()<br>.addAllUsers(UserData.getUsers())<br>.build();</pre><p><strong>Considerations:</strong></p><p><strong>Use Case:</strong></p><p><strong>GraphQL: </strong>Suitable for scenarios where clients need flexibility in requesting specific data and there is a need for a single flexible API endpoint.</p><p><strong>gRPC: </strong>Suitable for micro services architectures, especially when performance, efficiency, and strong typing are critical.</p><p><strong>Network Overhead:</strong></p><p><strong>GraphQL: </strong>JSON payloads can be larger compared to binary formats like Protocol Buffers, resulting in slightly higher network overhead.</p><p><strong>gRPC: </strong>Uses a binary format, reducing payload size and potentially improving network performance.</p><p><strong>Developer Experience:</strong></p><p><strong>GraphQL: </strong>Provides a more flexible and intuitive developer experience when exploring and querying the API.</p><p><strong>gRPC: </strong>May require a steeper learning curve due to Protocol Buffers and generated code, but can lead to a more disciplined and strongly typed development process.</p><p>Ultimately, the choice between GraphQL and gRPC depends on the specific requirements of the project, the nature of the data, and the desired trade-offs in terms of flexibility, performance, and developer experience. Both technologies have their strengths and are suitable for different use cases.</p><h4><strong>Benefits of utilizing GraphQL over Rest API and gRPC</strong></h4><p><strong>Selective Data Retrieval</strong></p><p>GraphQL refines REST queries, curbing over-fetching with tailored queries and dynamic schema exploration. Similarly, gRPC ensures precise data queries via protobuf schema, facilitating efficient client-side retrieval.</p><p><strong>Reduced Number of Requests</strong></p><p>GraphQL streamlines data retrieval, consolidating requests across REST APIs into a single efficient query, minimizing network latency. Similarly, gRPC boosts communication efficiency with HTTP/2 multiplexing, optimizing network resources by transmitting multiple messages through a single connection, reducing latency.</p><p><strong>Efficient for Frontend Development</strong></p><p>GraphQL enhances frontend flexibility in RESTful services, optimizing data transfer for single-page applications. Similarly, gRPC’ s robust features, including strong typing and code generation from the protobuf schema, boost frontend development efficiency, reduce errors, and ensure consistency across the application stack.</p><p><strong>Schema Stitching</strong></p><p>Schema stitching streamlines data consolidation in GraphQL and gRPC architectures. In GraphQL, it unifies multiple schemas or RESTful APIs for seamless data aggregation. Similarly, in gRPC, services merge into a unified GraphQL schema, shielding clients from micro services intricacies and promoting adaptable communication.</p><p><strong>Incremental Adoption</strong></p><p>GraphQL integrates smoothly into RESTful systems for specific functions, ensuring a gradual and seamless transition. Similarly, gRPC supports incremental adoption for specific functionalities or micro services, maintaining flexibility without disrupting the entire application.</p><p><strong>Real-time Functionality</strong></p><p>REST’s request-response model contrasts with GraphQL’ s real-time functionality through subscriptions and Web Sockets. Similarly, gRPC enables bidirectional streaming for seamless real-time communication, enhancing collaboration in applications.</p><p><strong>Hybrid Approaches</strong></p><p>Organizations adopt a hybrid approach, using REST for simplicity and industry standards in some system components, while employing GraphQL with gRPC for efficient communication in micro services. This flexibility allows developers to leverage the strengths of each protocol, creating a customized solution aligned with system architecture and business needs.</p><h4><strong>Where can we use GraphQL?</strong></h4><p>GraphQL exhibits versatility, finding utility in diverse applications. Its optimization of data transfer is notable in Single-Page Applications (SPAs), while it enhances network efficiency in mobile contexts. In micro services architectures, GraphQL functions as an abstraction layer, efficiently aggregating data from multiple sources. The real-time capabilities cater to applications requiring live updates, and its dynamic querying is adept at handling scenarios with intricate data relationships. GraphQL’ s flexibility facilitates rapid development, proving invaluable for prototyping purposes. Additionally, it excels in aggregating content from headless Content Management Systems (CMS) and is seamlessly integrated with prevalent frontend frameworks like React and Angular. Its efficacy in retrieving precise data is particularly advantageous for data-intensive applications, such as analytics dashboards. Overall, GraphQL stands out in scenarios demanding meticulous control over data retrieval, dynamic querying, and adaptability.</p><h4><strong>How easy to migrate REST API to GraphQL?</strong></h4><p>The migration process from a REST API to GraphQL demands meticulous planning and execution to ensure a seamless transition. A comprehensive understanding of GraphQL concepts, encompassing queries, mutations, types, and resolvers, is imperative for developers. The design of the GraphQL schema, reflecting the intricacies of data structure and application requirements, assumes a pivotal role. A significant milestone in the migration involves consolidating multiple RESTful endpoints into a unified GraphQL endpoint. Methodical planning is essential for key aspects such as data fetching strategies, query translation, and the establishment of standardized error-handling procedures. Authentication and authorization mechanisms require careful review and alignment with GraphQL standards. The adoption of GraphQL-specific tools and libraries is crucial for tasks such as validation and testing. Rigorous testing protocols for GraphQL queries and mutations are paramount to ensure the anticipated outcomes. Documentation for the GraphQL API, covering types, queries, and mutations, must be meticulously updated or created. Modification of client applications to facilitate the transmission of GraphQL queries necessitates adjustments to accommodate the novel data fetching mechanism. Employing an iterative approach to migration, beginning with a subset of functionality, facilitates a gradual and controlled adaptation process. Lastly, investing in education and training initiatives for the development team regarding GraphQL concepts and best practices significantly contributes to the overall success and efficiency of the migration.</p><h4><strong>Future scope of GraphQL</strong></h4><p>The future of GraphQL seems bright, with broad adoption and improved performance. Organizations are increasingly using it, particularly for mobile and bandwidth-sensitive applications. The technology is unique in that it allows developers to create responses in an intuitive manner through flexible data querying. Scalability is promoted by GraphQL’ s smooth integration with contemporary technologies like server less architectures and real-time systems. The growing ecosystem and tooling significantly simplify development. The GraphQL community is working to improve interoperability and streamline system integration through standardization efforts. GraphQL’ s future seems bright overall because of its widespread use, improved performance, adaptability in querying, technological integration, expanding ecosystem, and continuous efforts toward standardization.</p><h4><strong>Summary</strong></h4><p>In this comprehensive blog article, we delved into the intricacies of GraphQL, exploring its integration with REST API and gRPC, contrasting data fetching approaches between REST API, gRPC and GraphQL, and conducting a detailed comparison among GraphQL, REST, and gRPC. We elucidated the benefits of employing GraphQL alongside REST API, and contemplating the prospective applications of GraphQL in the evolving landscape of technology. This exploration will equip readers with a nuanced understanding of GraphQL’ s versatility and its potential impact on the future of API development.</p><h4><strong>Reference:</strong></h4><p><a href="https://graphql.org/">https://graphql.org/</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9e9a67c376c7" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>