That matters because OpenClaw is self-hosted, multi-channel, open source, and built around agent workflows such as sessions, tools, plugins, and multi-agent routing. It feels less like a toy chatbot and more like an operator-controlled agent runtime.

In this guide, you'll do three things. First, you'll learn what OpenClaw is and why developers are paying attention to it. Second, you'll get it running the beginner-friendly way through the dashboard. Third, you'll walk through an original design contribution: a proposed OpenClaw-to-A2A plugin architecture and a proof-of-concept relay that shows how OpenClaw’s session model could map to the A2A protocol.

That last part is important, so I want to frame it carefully. The A2A integration in this article is not presented as a built-in OpenClaw feature. It's a documented architecture proposal built on top of the extension points OpenClaw already exposes.

Prerequisites

This guide is beginner-friendly for OpenClaw itself, but it assumes a few basics so you can follow the architecture and proof-of-concept sections comfortably.

Before you continue, you should be familiar with:

• Basic JavaScript or Node.js (reading and running scripts)

• How HTTP APIs work (requests, responses, JSON payloads)

• Using a terminal to run commands

• High-level concepts like services, APIs, or microservices

You don't need prior experience with OpenClaw or A2A. The setup steps walk through everything you need to get started.

Table of Contents

1. What OpenClaw Is

2. Why OpenClaw Is Getting So Much Attention

3. What the A2A Protocol Is

4. How OpenClaw and A2A Relate

5. What You Need Before You Start

6. Install OpenClaw

7. Run the Onboarding Wizard

8. Check the Gateway and Open the Dashboard

9. Use OpenClaw as a Private Coding Assistant

10. Understand Multi Agent Routing

11. Where A2A Could Fit Later

12. A Proposed OpenClaw to A2A Plugin Architecture

13. Build the Proof of Concept Relay

14. How the Proof of Concept Maps to a Real OpenClaw Plugin

15. Security Notes Before You Go Further

16. Final Thoughts

What OpenClaw Is

According to the official docs, OpenClaw is a self-hosted gateway that connects chat apps like WhatsApp, Telegram, Discord, iMessage, and a browser dashboard to AI agents.

That wording is useful because it tells you where OpenClaw sits in the stack. It's not just a model wrapper. It's a Gateway that handles sessions, routing, and app connections, while agents, tools, plugins, and providers do the actual work.

Here is the simplest mental model:

If you're new to the project, this is the practical way to think about it:

• your chat apps are the front door

• the Gateway is the traffic and control layer

• the agent is the reasoning layer

• the model provider and tools are what let the agent actually do work

That's one reason OpenClaw feels different from a normal browser-only assistant.

Why Developers Are Paying Attention to OpenClaw

OpenClaw is getting a lot of attention for a few reasons.

The first reason is control. The docs position OpenClaw as self-hosted and multi-channel, which means you can run it on your own machine or server instead of depending on a fully hosted assistant.

The second reason is that OpenClaw already looks like an agent platform. The docs talk about sessions, plugins, tools, skills, multi-agent routing, and ACP-backed external coding harnesses. That's a much richer story than “ask a model a question in a web page.”

The third reason is workflow fit. A lot of people don't want another inbox. They want an assistant that can live in the tools they already check every day.

There's also a broader industry trend behind the hype. Developers are actively looking for ways to connect multiple agents and multiple tools without giving up visibility into what's happening. OpenClaw sits directly in that conversation.

What the A2A Protocol Is

A2A, short for Agent2Agent, is an open protocol for communication between agent systems. The A2A specification says its purpose is to help independent agent systems discover each other, negotiate interaction modes, manage collaborative tasks, and exchange information without exposing internal memory, tools, or proprietary logic.

That last point matters. A2A is about interoperability between agent systems, not about exposing all of one agent's internals to another.

A2A introduces a few core concepts that are worth learning early:

• Agent Card: a JSON description of the remote agent, its URL, skills, capabilities, and auth requirements

• Task: the main unit of remote work

• Artifact: the output of a task

• Context ID: a stable interaction boundary across multiple related turns

A2A tasks follow a fairly clean lifecycle:

The A2A docs also explain that A2A and MCP are complementary, not competing. A2A is for agent-to-agent collaboration. MCP is for agent-to-tool communication.

That distinction is useful when you compare A2A with OpenClaw, because OpenClaw already has strong local tool and session concepts.

How OpenClaw and A2A Relate

OpenClaw and A2A are not the same thing, but they line up in interesting ways.

OpenClaw already documents several features that point in a multi-agent direction:

• multi-agent routing for multiple isolated agents in one running Gateway

• session tools such as sessions_send and sessions_spawn

• a plugin system that can register tools, HTTP routes, Gateway RPC methods, and background services

• ACP support and the openclaw acp bridge for external coding clients

But it's still important to stay precise here.

OpenClaw documents ACP, plugins, and local multi-agent coordination today. The docs I checked do not describe native A2A support as a first-class built-in capability.

That means the honest claim is this:

OpenClaw can be meaningfully connected to A2A in theory because the architectural pieces line up, but the A2A bridge still has to be built.

ACP versus A2A

ACP and A2A solve different problems.

ACP in OpenClaw today is about bridging an IDE or coding client to a Gateway-backed session.

A2A is about one agent system talking to another agent system across a protocol boundary.

That difference is one reason I prefer the phrase plugin bridge here instead of native A2A support.

What You Need Before You Start

The easiest first run does not require WhatsApp, Telegram, or Discord.

The OpenClaw onboarding docs say the fastest first chat is the dashboard. That makes this a much more approachable beginner setup.

Before you start, you'll need:

1. Node 24 if possible, or Node 22.16+ for compatibility

2. an API key for the model provider you want to use

3. If you're on Windows, WSL2 is the recommended path for the full experience. Native Windows works for core CLI and Gateway flows, but the docs call out caveats and position WSL2 as the more stable setup.

4. about five minutes for the first dashboard-based run

Step 1: Install OpenClaw

The official getting-started page recommends the installer script.

On macOS, Linux, or WSL2, run:

curl -fsSL https://openclaw.ai/install.sh | bash

On Windows PowerShell, the docs show this:

iwr -useb https://openclaw.ai/install.ps1 | iex

If you're on Windows, the platform docs recommend installing WSL2 first:

wsl --install

Then open Ubuntu and continue with the Linux commands there.

Step 2: Run the Onboarding Wizard

Once the CLI is installed, run the onboarding wizard.

openclaw onboard --install-daemon

The onboarding wizard is the recommended path in the docs. It configures auth, gateway settings, optional channels, skills, and workspace defaults in one guided flow.

The most beginner-friendly choice is to keep the first run simple. Don't worry about chat apps yet. Get the local Gateway working first.

Step 3: Check the Gateway and Open the Dashboard

After onboarding, verify that the Gateway is running.

openclaw gateway status

Then open the dashboard:

openclaw dashboard

The docs call this the fastest first chat because it avoids channel setup. It's also the safest way to start, because the dashboard is local and the OpenClaw docs clearly say the Control UI is an admin surface and should not be exposed publicly.

The beginner setup flow looks like this:

If you can chat in the dashboard, your day-zero setup is working.

Step 4: Use OpenClaw as a Private Coding Assistant

The best first use case is not to drop OpenClaw into a public group chat.

Use it as a private coding assistant in the dashboard.

For example, try a prompt like this:

I am building a small Node.js utility that reads Markdown files and generates a table of contents. Turn this idea into a project plan, a README outline, and the first five implementation tasks.

That kind of prompt is ideal for a first run because it gives you something concrete back right away.

You can also use it to:

1. turn rough notes into a plan,

2. summarize a bug report into action items,

3. draft a README,

4. propose a folder structure, or

5. write a safe first implementation checklist.

That is already enough to make OpenClaw useful before you touch any advanced protocol work.

Step 5: Understand Multi Agent Routing

Once the basic setup is working, it helps to understand OpenClaw’s local multi-agent model.

The docs describe multi-agent routing as a way to run multiple isolated agents in one Gateway, with separate workspaces, state directories, and sessions.

That means you can imagine setups like this:

• a personal assistant

• a coding assistant

• a research assistant

• an alerts assistant

OpenClaw already has a model for that:

You don't need to set this up on day one.

But it matters for the A2A discussion, because once you understand how OpenClaw routes work between local agents, it becomes much easier to think about routing work to remote agents through a protocol like A2A.

Where A2A Could Fit Later

A2A could fit into OpenClaw in two broad ways.

Option 1: OpenClaw as an A2A Client

In this model, OpenClaw stays your personal edge assistant.

It receives a request from the dashboard or a chat app, decides the task needs a specialist, discovers a remote A2A agent through an Agent Card, sends the task, waits for updates or artifacts, and translates the result back into a normal OpenClaw reply.

This is the cleaner story for a personal assistant. OpenClaw stays the front door, and A2A becomes a delegation path behind the scenes.

Option 2: OpenClaw as an A2A Server

In this model, OpenClaw exposes some of its own capabilities to other agents.

A plugin could theoretically publish an A2A Agent Card, advertise a narrow skill set, accept A2A tasks, and map those tasks into OpenClaw sessions or sub-agent runs.

That's technically plausible because the plugin system can register HTTP routes, tools, Gateway methods, and background services.

It's also the riskier direction for a personal assistant, which is why I think client-first is the right starting point.

A Proposed OpenClaw to A2A Plugin Architecture

This section is my original contribution in the article.

I think the cleanest first architecture is not a full bidirectional bridge. It's a narrow outbound delegation plugin that lets OpenClaw call a small allowlist of remote A2A agents.

The design goal is simple:

Reuse OpenClaw for user-facing conversations and local tool access, but use A2A only when a remote specialist agent is the best place to do the work.

Here is the architecture I would start with:

Why This Design is a Good Fit for OpenClaw

This proposal is grounded in extension points OpenClaw already documents.

A plugin can register:

• an agent tool for delegation,

• a Gateway method for health and diagnostics,

• an HTTP route for future callbacks or webhook verification, and

• a background service for cache warming, task subscriptions, or cleanup.

That means the bridge doesn't have to modify OpenClaw core to be credible.

The Mapping Table

The most important design decision is how to map OpenClaw’s session model to A2A’s task model.

Here is the mapping I recommend:

This is the key architectural claim in the article:

Treat the OpenClaw session as the long-lived conversational boundary, and treat each remote A2A task as one delegated execution inside that boundary.

That preserves both sides cleanly.

The Design in One Sentence

The a2a_delegate tool should:

1. resolve an allowlisted remote Agent Card,

2. reuse an existing A2A contextId for the current sessionKey when possible,

3. create a fresh remote Task for the new delegated turn,

4. normalize remote artifacts back into a simple local answer, and

5. never expose the whole OpenClaw Gateway directly to the public internet.

I like this design because it is incremental, testable, and consistent with OpenClaw’s personal-assistant trust model.

Build the Proof of Concept Relay

To make the architecture concrete, I built a small proof-of-concept relay.

https://github.com/natarajsundar/openclaw-a2a-secure-agent-runtime

It's intentionally small. It doesn't try to become a full production plugin. Instead, it proves the hardest conceptual part of the bridge: how to map one OpenClaw session to a reusable A2A context while creating a fresh A2A task per delegated turn.

Here's the repository layout:

openclaw-a2a-secure-agent-runtime/
├── README.md
├── package.json
├── examples/
│   └── openclaw-plugin-entry.example.ts
├── src/
│   ├── a2a-client.mjs
│   ├── agent-card-cache.mjs
│   ├── demo.mjs
│   ├── mock-remote-agent.mjs
│   ├── openclaw-a2a-relay.mjs
│   ├── session-task-map.mjs
│   └── utils.mjs
└── test/
    └── relay.test.mjs

The PoC does six things:

1. fetches a remote Agent Card from /.well-known/agent-card.json,

2. caches it with simple ETag revalidation,

3. records local sessionKey to remote contextId mappings,

4. sends an A2A SendMessage request,

5. polls GetTask until the task finishes, and

6. converts the remote artifact into a local text answer.

Run the Demo

The repo uses only built-in Node.js modules.

cd openclaw-a2a-secure-agent-runtime
npm run demo

The demo spins up a mock remote A2A server, delegates one task, delegates a second task from the same local session, and shows that the same remote contextId is reused.

The Core Relay Idea

This is the important logic in plain English:

1. look up the most recent remote mapping for the current OpenClaw sessionKey

2. reuse the old contextId if one exists

3. create a fresh A2A Task for the new request

4. poll until that task becomes TASK_STATE_COMPLETED

5. turn the returned artifact into a normal text result that OpenClaw can send back to the user

That makes the bridge predictable.

Here's a shortened version of the relay logic:

const previous = await sessionTaskMap.latestForSession(sessionKey, remoteBaseUrl);
const contextId = previous?.contextId ?? crypto.randomUUID();

const sendResult = await client.sendMessage({
  text,
  contextId,
  metadata: {
    openclawSessionKey: sessionKey,
    requestedSkillId: skillId,
  },
});

let task = sendResult.task;
while (!isTerminalTaskState(task.status?.state)) {
  await sleep(pollIntervalMs);
  task = await client.getTask(task.id);
}

return {
  contextId,
  taskId: task.id,
  answer: taskArtifactsToText(task),
};

That's the heart of the design.

Why This Repo is a Useful Proof of Concept

A lot of “integration” articles stay too abstract. This repo avoids that problem in three ways.

First, it makes the session-to-context mapping explicit.

Second, it includes a mock remote A2A agent so you can test the flow without needing a large external setup.

Third, it includes a test that checks the most important invariant: repeated delegations from one local OpenClaw session reuse the same A2A context.

That is the piece I most wanted to make concrete, because it is where architecture turns into implementation.

How the Proof of Concept Maps to a Real OpenClaw Plugin

The proof of concept is the relay core.

A real OpenClaw plugin would wrap that relay with four extension surfaces that the OpenClaw docs already describe.

1: A Delegation Tool

This is the main entry point.

A plugin would register an optional tool like a2a_delegate so the local agent can explicitly choose to delegate work.

That tool should be optional, not always-on, because remote delegation is a side effect and should be easy to disable.

2: A Gateway Method for Diagnostics

A method like a2a.status would let you inspect whether the relay is healthy, which remote cards are cached, and whether any tasks are still being tracked.

That is much better than asking the model to “tell me if the bridge is healthy.”

3: A Plugin HTTP Route

You may not need this on day one.

But once you move beyond polling and want push-style callbacks or webhook verification, a plugin route gives you the right boundary for that work.

4: A Background Service

A small service is a clean place to do cache warming, cleanup, or later subscription handling.

That keeps the tool path focused on delegation instead of maintenance work.

If I were turning this into a real plugin package, I would sequence the work in this order:

1. wrap the relay in registerTool,

2. add a small config schema with an allowlist of remote agents,

3. add a2a.status,

4. keep polling as the first async model,

5. add a callback route only if a real use case needs it.

That is the most practical path from theory to a real extension.

I tested the relay flow locally with the mock remote agent and confirmed that repeated delegations from the same local session reused the same remote contextId.

Security Notes Before You Go Further

This is the section you should not skip.

The OpenClaw security docs explicitly say the project assumes a personal assistant trust model: one trusted operator boundary per Gateway. They also say a shared Gateway for mutually untrusted or adversarial users is not the supported boundary model.

That has a direct consequence for A2A.

A2A is designed for communication across agent systems and organizational boundaries. That is powerful, but it is also a different threat model from a single private OpenClaw deployment.

So the safer design is not this:

• expose your personal OpenClaw Gateway publicly,

• let arbitrary remote agents reach it,

• and hope the tool boundaries are enough.

The safer design is closer to this:

This diagram shows two separate trust boundaries.

On the left is your private OpenClaw deployment. This includes your Gateway, your sessions, your workspace, and any credentials or tools your agent can access. This boundary is designed for a single trusted operator.

On the right is the external A2A ecosystem, where remote agents live. These agents may belong to other teams or organizations and operate under different security assumptions.

The key idea is that communication between these two sides should happen through a controlled relay layer, not by directly exposing your OpenClaw Gateway. The relay enforces allowlists, limits what data is sent out, and ensures that remote agents cannot directly access your local tools or state.

This separation lets you experiment with agent interoperability while keeping your personal assistant environment safe.

In plain English, keep your personal assistant boundary private.

If you experiment with A2A, treat that as a separate exposure boundary with its own allowlists, auth, and operational controls.

That is why the proof-of-concept relay in this article starts with an explicit remote allowlist.

Why This Design and Not the Other One?

A natural question is why this article proposes an outbound-only A2A bridge first, instead of immediately building a full bidirectional or server-style integration.

The short answer is that OpenClaw’s current design is centered around a personal assistant trust boundary, where one operator controls the Gateway, sessions, and tools. Introducing external agents into that environment requires careful control over what is exposed.

Starting with outbound delegation gives you a safer and more incremental path.

Outbound-only first means:

• preserving the personal-assistant trust boundary, so your local OpenClaw deployment remains private and operator-controlled

• avoiding exposing the OpenClaw Gateway as a public A2A server before you have strong auth, policy, and monitoring in place

• allowing you to test remote delegation patterns (Agent Cards, tasks, artifacts) without committing to full interoperability complexity

• keeping OpenClaw as the user-facing control plane, while remote agents act as optional specialists

This approach follows a common systems design pattern: start with controlled outbound integration, validate behavior and constraints, and only then consider expanding to inbound or bidirectional communication.

In practice, this means you can experiment with A2A safely, learn how the models fit together, and evolve the system without introducing unnecessary risk early on.

Final Thoughts

OpenClaw is worth learning because it gives you a self-hosted assistant that can live in the communication tools you already use.

The simplest beginner path is still the right one:

1. install it,

2. run onboarding,

3. check the Gateway,

4. open the dashboard,

5. try one private workflow.

That is already a real end-to-end setup.

A2A belongs in the conversation because it gives you a credible way to connect OpenClaw to remote specialist agents later.

But the most important thing in this article isn't the buzzword. It's the boundary design.

If you keep OpenClaw as the private user-facing edge and use a narrow plugin bridge for outbound delegation, the OpenClaw session model and the A2A task model can fit together cleanly.

That is the architectural idea I wanted to make concrete here.

Diagram Attribution

All diagrams in this article were created by the author specifically for this guide.

Further Reading

• OpenClaw docs home

• OpenClaw Getting Started

• OpenClaw Onboarding Wizard

• OpenClaw Multi-Agent Routing

• OpenClaw Session Tools

• OpenClaw Plugin System

• OpenClaw Plugin Agent Tools

• OpenClaw ACP bridge

• OpenClaw Security

• A2A specification

• A2A Agent Discovery

• A2A and MCP

• A2A protocol definition and schema

• A2A version 1.0 announcement

To make things even worse, how about a CORS error that completely prevented you from showing the page?

It happens, right? Going back to the backend team and getting a quick fix for these issues would be ideal, but may not be realistic in most cases. It depends on the availability of the backend developers, the priority items they're working on, communication protocols between teams, and even interpersonal relationships.

Now, the question is, can you afford to wait? Wait for things to work in your favour within the given deadline so that you can show that demo or deliver the work to your customer? The answer is NO. You may not have that luxury.

Today, in this article, you'll learn a couple of mind-blowing tips and tricks that will save you from these situations. You'll understand how to set up your Chrome browser so that you can continue with your frontend development even when the backend API returns an incorrect response or a CORS error.

This is a step-by-step guide that'll help make you comfortable with all the required configurations and get you set up to use it on your web projects. This guide is also available as a video tutorial as part of the Thinking in Debugging series. You can check it out if you’d like:

Let's get started with the problems and their solutions.

Table of Contents

1. Problem 1: The Backend Response Is Wrong

2. Problem 2: Validating a UI Scenario Without Backend Changes

3. Problem 3: Handling CORS Errors

4. Additional Tips

   • Applying Overrides Globally

   • Disabling or Removing Overrides

5. Learn More From the Thinking in Debugging Mindset

6. Before We End…

Problem 1: The Backend Response Is Wrong

Here is a classic case of a wrong API response, but you still need to continue with your frontend work.

Take a look at the image below. Do you see that something is off? Yeah, on the first card, the spelling of Banana seems to be misspelled as Banananana. This user interface is constructed using the data we have received as an API response.

We can go to the backend team and request that they fix it as soon as possible. But it may not happen until the next sprint starts, which might be 15 days from now.

So, what can we do to continue with our work and all the validations on the frontend side? We can use the Content Overriding feature of the Chrome browser to mitigate this situation.

How to Use Content Overriding

First, open up the DevTools of your Chrome browser by pressing the F12 (on Mac, Cmd+F12) key. Then move to the network tab and inspect the API request that returns the incorrect response.

Next, right-click on the API request and select the Override content option from the context menu.

You may wonder what content means here, and what I am overriding? You're overriding the API response so that it can reflect on the UI locally.

This will bring up a UI at the top where you can select a folder to store override files. It's important to understand that all the content overrides are locally stored on your machine's hard disk. This means you can use these persisted overrides again and again until someone fixes the issue permanently at the backend.

Now click on the Select folder button.

This will open up the folder explorer for you. Create a new folder and select it, or select an existing folder where you want to save the overrides. In my case, I've named the folder as debug_devtools.

Now, Chrome DevTools will ask for confirmation that you're allowing DevTools to edit files on your local system. Just click on the Allow button.

That's all for the setup. Now, you'll find the same response in the editable mode under the Sources tab of DevTools. Let's take a deeper look at the image below:

1. The Local overrides are listed under the Sources > Oveerides tab of the DevTools.

2. On the left side, the Enable Local Overrides checkbox is selected, and the overrides are listed below. You can find the same folder you created before, and under that, you'll see another folder called localhost:3001 and a file called edibles under it. The localhost:3001 folder name is related to the API endpoint namespace we're connecting to. The edibles file name under it goes with the request name.

3. On the right side, you can see the content (that is, the response to the edibles request) in editable mode.

You can even cross-check now by traversing to the file system's debug_devtools folder. You should find the same folders and files as you saw in the DevTools.

You can open up the edibles file. The file content should match exactly the response you saw before.

Now, it's time to override. Coming to the Sources tab's editable response panel, you can fix the spelling. Save your changes using Ctrl + S (or Cmd + S).

Now, hard refresh your browser. You should be able to see your change reflected on the UI.

Awesome!! You can now share this overridden response (the edibles file) with other developers to point to from their Chrome DevTools to get the same local fix until the backend fixes it.

Problem 2: Validating a UI Scenario Without Backend Changes

Imagine you need to validate that certain items are low in stock on an item listing page. If the stock quantity of an item hits 50 or below, you want to show a Low Stock label for that item.

Now, what if the API response doesn't return a quantity of 50 or below? Content overriding can come to the rescue once again!

You can edit the response to set the quantity value to 50 or below and follow the same process as before to reflect the change on the UI. Look at the image below:

1. We have edited the quantity on the right-side panel.

2. Once saved and refreshed, we not only see the updated count on the UI, but it also runs the underlying JavaScript logic to show the Low Stock label automatically. This is a superpower.

Problem 3: Handling CORS Errors

Cross-Origin Resource Sharing (CORS) is a browser security feature that allows a web server to explicitly grant requests coming from a domain other than its own. By default, browsers don't allow these cross-origin requests and follow a strict rule called Same Origin Resource Sharing.

In many cases, your API server and the web server could be hosted on different domains. In those cases, when the web application attempts to access an API, it faces the CORS error.

On the server side, you need to have explicit configurations to allow cross-origin requests. For example, you need to add the following response headers:

Access-Control-Allow-Origin: http://localhost:5174
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: *

So, again, it may not be guaranteed that your CORS error will be resolved at the server side as soon as you want. But you cann't afford to get blocked due to it. So, what's the way around? Yes! The overriding, but this time, overriding the response header.

Go to the network tab of the Chrome DevTools and right-click on the request that has the CORS error. Now, select the Override headers option from the context menu.

By the way, have you noticed that the Override content option is disabled here? This is because we don't have any response as content from this request, as it got an error.

Clicking on the Overriding headers will take you to the Headers tab where you can find the option to add additional headers to the response headers. Click on the + Add header button to add the CORS-related headers.

Add all three headers with their respective values one by one:

Access-Control-Allow-Origin: http://localhost:5174 
Access-Control-Allow-Methods: GET 
Access-Control-Allow-Headers: *

Each of these headers has its own important use:

1. With the Access-Control-Allow-Origin header, you can specify the origin domains that are allowed to have a cross-origin request to the server. In this case, the value is http://localhost:5174 where we're running a Vite-based ReactJS app.

2. The header Access-Control-Allow-Methods specifies what kind of HTTP methods are allowed from the originating domain. In this case, we're allowing only the GET method.

3. The Access-Control-Allow-Headers HTTP response headers specify which HTTP headers can be safely used during a cross-origin request.

Alright, let's add them all and save.

Like overriding content, overriding the header will also create a folder with the context of the server domain, and under that, a file called .headers. As the file name starts with a dot(.), it may be treated as a hidden file by most operating systems. So make sure you go through the OS settings to view the hidden files to view this file.

Once you view and open the file, you'll see the headers you have added with overriding.

Now, hard refresh your browser, and try to perform the same operation that was giving you the CORS error before. Wow, the error has gone now! You should be able to see the request success and the response coming back from the server.

Just imagine, not a single line of server-side code changes, and you're unblocked so you can move forward with your client-side UI work. Fantastic, isn't it?

Additional Tips

Before we end, let's learn about a couple more handy tips.

Applying Overrides Globally

We applied the CORS error-related header overriding only on the /user API endpoint. What if you need to apply the same overriding for other endpoints, too? You can do it easily by following these simple steps:

1. Navigate to the Sources tab.

2. Select the Overrides sub-tab.

3. Click on the .headers override.

4. On the right-side panel, change the value of the Apply to to *.

That's it. Now, the same response headers will be applied as overrides for all the endpoints.

Disabling or Removing Overrides

Sometimes, you might want to disable or remove overrides. To disable overrides without removing them, just uncheck the Enable Local Overrides checkbox. To remove all the overrides permanently, click on the stop icon at the top-right corner. Also, to selectively remove an override, right-click on it and delete.

Learn More From the Thinking in Debugging Mindset

If you've liked this practical, example-driven guide, you'll enjoy my other debugging-related content from the Thinking in Debugging series. Please check it out.

Before We End…

That’s all! I hope you found this insightful.

Let’s connect:

• Subscribe to my YouTube Channel.

• Check out my courses, 40 Days of JavaScript and 15 Days of React Design Patterns

• Follow on LinkedIn if you don't want to miss the daily dose of up-skilling tips.

• Join my Discord Server, and let’s learn together.

• Follow my work on GitHub.

See you soon with my next article. Until then, please take care of yourself and keep learning.

For years, developers logged into dashboards, clicked through forms, and configured servers by hand. This worked for small projects, but it quickly became fragile. Every manual step increased the chance of mistakes. Environments drifted apart. Reproducing the same setup became difficult.

Infrastructure as Code (IaC) solves this problem. Instead of clicking through interfaces, developers define infrastructure using code. This approach makes infrastructure predictable, repeatable, and easy to automate.

In recent years, another approach has become popular alongside traditional IaC tools: using cloud APIs directly to create and manage infrastructure. This gives developers full control over how resources are provisioned and integrated into workflows.

This article explains what Infrastructure as Code means, why APIs are a powerful way to implement it, and how developers can automate cloud resources using simple scripts.

A basic understanding of cloud platforms, command-line interfaces, and scripting languages like Python, Bash, or JavaScript will help you follow along effectively. Familiarity with APIs, authentication methods, and CI/CD concepts will also make it easier to implement the automation techniques discussed in this article.

Here's what we'll cover:

• What Is Infrastructure as Code?

• The Limits of Manual Infrastructure

• Why APIs Are a Powerful IaC Tool

• Automating Infrastructure with Scripts

• Practical Example with Sevalla

  • Installing CLI

  • Working with your Infrastructure using CLI

• Infrastructure as Code Improves Developer Productivity

• The Future of Infrastructure

• Conclusion

What Is Infrastructure as Code?

Infrastructure as Code means managing infrastructure using code instead of manual processes.

Instead of setting up servers, databases, and networks by hand, you define them in scripts or configuration files. These files describe the desired state of your infrastructure. A tool or script then creates and maintains that state automatically.

For example, instead of manually creating a database, you might define it in code like this:

database:
  name: app_db
  engine: postgres
  version: 16

Once the code runs, the database is created automatically.

This approach provides several key benefits.

First, it improves consistency. Every environment is created from the same definition. Development, staging, and production environments stay aligned.

Second, it improves repeatability. If infrastructure fails, it can be recreated from code in minutes.

Third, it improves version control. Infrastructure definitions live in the same repositories as application code. Teams can review, track, and roll back changes.

Finally, it enables automation. Infrastructure can be created during deployments, tests, or CI/CD pipelines.

The Limits of Manual Infrastructure

Before IaC became common, infrastructure management relied heavily on dashboards and manual configuration.

A developer would open a cloud console and perform steps like:

• Create a server

• Attach storage

• Configure environment variables

• Connect a database

• Add a domain

These steps worked, but they introduced problems.

First of all, manual configuration is hard to document. Even if teams write guides, small details are often missed. Over time, environments drift apart.

Manual processes also slow down development. Spinning up a new environment may take hours instead of seconds.

Even worse, manual infrastructure cannot easily be tested. If something breaks, reproducing the same conditions becomes difficult.

Infrastructure as Code removes these problems by turning infrastructure into something that can be scripted, tested, and automated.

Why APIs Are a Powerful IaC Tool

Many people associate Infrastructure as Code with tools like Terraform or CloudFormation. These tools are powerful, but they're not the only option.

Every modern cloud platform exposes an API. That API allows developers to create resources programmatically.

This means infrastructure can be controlled directly from code using HTTP requests or command-line interfaces.

Using APIs for IaC has several advantages.

First, it offers maximum flexibility. Developers can integrate infrastructure creation directly into applications, deployment scripts, or internal tools.

Second, it reduces tooling complexity. Instead of learning a specialized IaC language, teams can use languages they already know, such as Python, JavaScript, or Bash.

Third, it enables dynamic infrastructure. Scripts can create resources only when needed, scale them automatically, and remove them when work is complete.

For example, a test suite could automatically create a database, run tests, and delete the database afterwards. This keeps environments clean and reduces costs.

APIs essentially turn the cloud into a programmable platform.

Automating Infrastructure with Scripts

Using APIs for infrastructure automation usually follows a simple workflow.

1. First, a script authenticates with the cloud platform using an API token or credentials.

2. Second, the script sends requests to create or modify resources such as applications, databases, or storage.

3. Third, the script captures identifiers or configuration values from the response.

4. Finally, those values are used in later steps, such as deployments or integrations.

Because these steps run in code, they can easily be included in CI/CD pipelines.

A typical pipeline might do the following:

• Create infrastructure

• Deploy the application

• Run tests

• Collect metrics

• Destroy temporary environments

This approach ensures every deployment follows the same process.

Practical Example with Sevalla

A practical way to apply Infrastructure as Code through APIs is to use a command-line interface that directly interacts with a cloud platform’s API. This lets you automate infrastructure creation using scripts rather than dashboards.

One example is the Sevalla CLI, which exposes infrastructure operations as terminal commands that can be executed manually or inside automation pipelines.

Sevalla is a developer-centric PaaS designed to simplify your workflow. They provide high-performance application hosting, managed databases, object storage, and static sites in one unified platform.

Other options are AWS and Azure, which require complex CLI tools and heavy DevOps overhead. Sevalla offers simplicity and ease of use, similar to Heroku.

Installing CLI

You can install the CLI using the following shell command:

bash <(curl -fsSL https://raw.githubusercontent.com/sevalla-hosting/cli/main/install.sh)

Once installed, you can view the list of all available commands using the help command:

The first step is authentication. Make sure you have an account on Sevalla before using the CLI.

sevalla login

For automated environments such as CI/CD pipelines, authentication can be done with an API token. The token is stored in an environment variable so scripts can run without user interaction.

export SEVALLA_API_TOKEN="your-api-token"

Once authenticated, you can quickly view a list of your apps using sevalla apps list

Working with Your Infrastructure using CLI

Your infrastructure can now be created directly from the command line. For example, you might start by creating an application service that will run the backend code:

sevalla apps create --name myapp --source privateGit --cluster <id>

This command provisions a new application resource on the platform. Instead of navigating through a web interface and filling out forms, the entire setup is performed through a single command.

Because the command can be stored in scripts or configuration files, it becomes part of the project’s infrastructure definition.

After creating the application, you'll often need a database. You can also provision this programmatically:

sevalla databases create \
  --name mydb \
  --type postgresql \
  --db-version 16 \
  --cluster <id> \
  --resource-type <id> \
  --db-name mydb \
  --db-password secret

This creates a PostgreSQL database with a defined version and credentials. In an automated workflow, the database creation step could run during environment setup for staging or testing.

Once the application and database exist, the next step might be configuring environment variables so the application can connect to the database:

sevalla apps env-vars create <app-id> --key DATABASE_URL --value "postgres://..."

These configuration values can be injected during deployments, ensuring the application always receives the correct settings.

Deployment automation is another key part of Infrastructure as Code. Instead of manually triggering deployments, a script can deploy new code whenever a repository is updated.

sevalla apps deployments trigger <app-id> --branch main

This allows CI/CD systems to deploy new versions of the application automatically after tests pass.

Infrastructure automation also includes scaling and monitoring. For example, if an application needs more instances to handle traffic, you can update the number of running processes programmatically.

sevalla apps processes update <process-id> --app-id <app-id> --instances 3

You can also retrieve metrics through the CLI. This allows monitoring tools or scripts to analyze system performance.

sevalla apps processes metrics cpu-usage <app-id> <process-id>

Similarly, you can also query application metrics such as response time or request rates to detect performance issues.

Another common step in infrastructure automation is configuring domains. Instead of manually linking domains to applications, a script can add them during environment setup.

sevalla apps domains add <app-id> --name example.com

With these commands combined in scripts or pipelines, you can fully automate the lifecycle of your infrastructure. A CI pipeline could create an application, provision a database, configure environment variables, deploy code, attach a domain, and monitor performance  – all without human intervention.

Because every command supports JSON output, scripts can also capture values returned by the platform and reuse them in later steps. For example:

APP_ID=$(sevalla apps list --json | jq -r '.[0].id')

This ability to chain commands together makes it easy to build powerful automation workflows.

In practice, teams often place these commands inside deployment scripts or pipeline steps. Whenever code is pushed to a repository, the pipeline automatically provisions or updates the infrastructure needed to run the application.

This approach demonstrates how APIs and automation tools can turn infrastructure into something you can manage the same way you manage application code: through scripts, version control, and automated workflows.

Infrastructure as Code Improves Developer Productivity

One of the biggest benefits of Infrastructure as Code is developer productivity.

Developers no longer need to wait for infrastructure changes or manually configure environments.

Instead, infrastructure becomes part of the development workflow.

When a new feature requires a service, the developer simply adds the infrastructure definition to the repository. The pipeline then creates it automatically.

This reduces delays and keeps development moving quickly.

It also makes onboarding easier. New team members can spin up a full environment with a single command.

The Future of Infrastructure

Cloud infrastructure continues to evolve toward automation and programmability.

Platforms increasingly expose APIs that allow every resource to be created, configured, and monitored through code.

This trend aligns naturally with the way developers already work.

Applications are built with code. Deployments are automated with code. It makes sense that infrastructure should also be defined with code.

Infrastructure as Code with APIs takes this idea even further. It allows infrastructure to be embedded directly into development workflows, pipelines, and internal tools.

The result is faster development, fewer configuration errors, and more reliable systems.

Conclusion

Infrastructure as Code has transformed how teams manage cloud environments.

By replacing manual configuration with code, organizations gain consistency, automation, and repeatability.

Using APIs to control infrastructure adds another level of flexibility. Developers can integrate infrastructure directly into scripts, pipelines, and applications.

This approach turns the cloud into a programmable platform.

As systems grow more complex and deployment cycles accelerate, the ability to automate infrastructure will only become more important.

For modern development teams, treating infrastructure as code is no longer optional. It's the foundation of reliable and scalable software delivery.

Hope you enjoyed this article. Learn more about me by visiting my LinkedIn.

Without API documentation, application development is considered incomplete because developers cannot build software to interact with it, rendering the application effectively useless.

In this article, you will learn how to create beautiful REST API documentation that also allows you to test the APIs for free using an OpenAPI specification and Scalar in Node.js projects. You will use asteasolutions/zod-to-openapi to generate OpenAPI specification and use Scalar to create a web page from the specification.

To get the most out of this article, you should have experience developing REST APIs with Express or NestJS. You should also have experience with documenting REST APIs and using zod.

Table of Contents

• REST API Documentation Tools for Node.js

  • Swagger

  • Postman

  • ReDoc

• zod-to-openapi and Scalar for REST API Documentation

  • How zod-to-openapi Works with Scalar

• Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation

  • OpenAPI Specification Support

  • Open Source and Free to Use

  • Better Documentation Experience

  • Developer-friendly UI

  • Markdown Support

• How to Create the API Documentation

  • Set up the Project

  • How to Set Up zod-to-openapi

  • How to Generate the Documentation UI with Scalar

  • Document the Endpoints

• How to Use Scalar with NestJS

• How to Resolve Content Security Policy (CSP) Errors When Used with Helmet

• Absence of AsyncAPI Documentation Feature

• Conclusion

REST API Documentation Tools for Node.js

A variety of tools already exist for documenting REST APIs and they have different strengths and weaknesses depending on their use case. While some of them are completely free to use, others operate a freemium model, and while some have an interface for testing APIs, others have a presentation-only user interface (UI).

Some of the most popular tools for documenting REST APIs in Node.js projects are listed below:

• Swagger

• Postman

• Redoc

Swagger

In order to document REST APIs in Express with Swagger, you need swagger-jsdoc and swagger-express-ui. swagger-jsdoc collates and parses JSDoc-annotated documentation comments in the codebase and generates an OpenAPI specification document. swagger-ui-express uses the generated document to created a web page that renders the API documentation and test the APIs.

One of Swagger’s strengths lies in its support for the OpenAPI specification which is an industry standard. Swagger is free to use, has a vibrant open source community and strong support for many programming languages and frameworks. It supports only REST APIs.

Its major drawback is the poor developer experience in manually writing JSDoc comments or YAML for the documentation. The process can be clumsy and developers can forget to include some annotations. Another drawback is that the JSDoc comments can interfere with reading functional code. Lastly, some developers have complained about its boring UI.

Postman

Postman is a cloud-based desktop API client application that allows developers and technical writers to write, test, collaborate on and publish API documentation. Unlike Swagger, it does not require deep programming experience to use most of its features. It is also not limited to REST API documentation — it can document APIs for GraphQL, websockets and gRPC.

Postman provides a UI to fill in details of an API documentation. The documentation process is manual and sometimes, its content can get out of sync with that of deployed applications. It is not free to use for teams and collaboration and hides the real behaviour of browser interaction with the APIs like CORS and streaming.

ReDoc

ReDoc is an open-source tool used to generate API documentation from an OpenAPI (Swagger) specification. It supports GraphQL, AsyncAPI and the OpenAPI specification and it renders a more beautiful documentation than Swagger. redoc-express is used to document Express REST APIs with Redoc.

Redoc’s major drawback is that its free community edition is presentation-only. It does not support testing the APIs. Similar to Swagger, a drawback it has is manually updating the application's OpenAPI document via a YAML specification file or JSDoc comments.

zod-to-openapi and Scalar for REST API Documentation

asteasolutions/zod-to-openapi is a TypeScript library that generates OpenAPI specification from zod schemas. It provides typed methods which serve as guardrails for documenting API components instead of using code comments so that:

• The library methods serve as guardrails for what to document and how to document it

• The documentation is consistent across the codebase

• The documentation doesn't negatively affect code readability

A sample snippet used to document a POST request for creating a user with zod-to-openapi is shown below:

// CreateUser and User are zod schema

registry.registerPath({
  method: "post",
  path: "/api/users",
  summary: "Create user",
  tags: ["users"],
  request: {
    body: {
      content: {
        "application/json": {
          schema: schema.CreateUser, 
        },
      },
      description: "Create user payload",
      required: true,
    },
  },
  responses: {
    201: {
      description: "User created",
      content: {
        "application/json": {
          schema: z.object({
            message: z.string(),
            data: schema.User,
          }),
        },
      },
    },
  },
});

Scalar is a tool that generates beautiful, organized and searchable API documentation from OpenAPI documents. The documentation generated also supports testing the APIs and this makes Scalar effectively function as an API documentation generator and a lightweight API client. The image below shows a sample documentation generated by Scalar:

How zod-to-openapi Works with Scalar

zod-to-openapi provides the functionality to generate an OpenAPI specification from code. Scalar uses the document generated to create a documentation web page that presents the information in the document in an organized and beautiful way that also allows for testing the APIs.

Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation

When you combine zod-to-openapi and Scalar to create REST API documentation for your Express applications, you get a myriad of benefits. Some of the benefits are explained below:

OpenAPI Specification Support

The OpenAPI specification is a format for describing REST APIs. It takes takes into consideration the important components of an API necessary for clients to use it effectively. These components include:

• Request paths, methods, headers, path parameters and query parameters,

• Schemas of request and response payloads,

• Authentication requirements,

• Descriptions for information not accommodated by other components

zod-to-openapi provides methods for all of these to be included in the documentation and it generates an OpenAPI specification-compliant document that Scalar uses to generate the documentation web page.

Open Source and Free to Use

zod-to-openapi is open source and free to use. It has no plans to be unsupported or sunsetted soon because like Ruby on Rails and Laravel, the creators of the project use it in their day-to-day work.

Scalar is open source too. It has paid plans but the features in the paid plans are only really useful for enterprise applications. The free version supports the necessary features needed to create useful REST API documentation.

Better Documentation Experience

In terms of user experience, the union of zod-to-openapi and Scalar provides the following benefits when writing documentation with both tools:

Guardrails with zod-to-openapi Methods

The methods provided by zod-to-openapi serve as guardrails to ensure that developers don't omit or forget the documentation of important components of APIs. The methods also ensure that these components are documented in an OpenAPI specification-compliant manner through the typed nature of the methods' parameters.

Avoid the Clumsiness of Comments and YAML Files

With zod-to-openapi, you don't document the APIs using comments or a YAML file. You document APIs using methods from zod-to-openapi. This removes the cluttering of code with comments and the clumsiness around manually updating large YAML files of OpenAPI specification.

Accuracy and Auto-generation of Documentation

When you use zod-to-openapi and Scalar, your API documentation is generated automatically when the application runs. zod-to-openapi does the collation and compilation of the documented APIs, and Scalar creates a web page for it that can be hosted on an API route of the same application. You don't need to manually run CLI commands to generate the documentation.

Another benefit of accuracy and auto-generation is that the job of API documentation is not split between technical writer and backend developer. The documentation is in the code and this makes development faster and more seamless in terms of API documentation.

Developer-friendly UI

While Swagger’s UI is functional, some developers consider its presentation somewhat minimal, particularly when displaying detailed endpoint descriptions. ReDoc improves on visual design but does not offer API testing features. Scalar, on the other hand, delivers a more refined and intuitive interface with greater customization options than ReDoc.

Beyond its design advantages, Scalar provides auto-generated code samples in multiple programming languages. This enables developers to integrate APIs more efficiently using examples tailored to their specific tech stack.

Scalar's UI provides a search feature that allows developers to quickly locate specific sections of the API documentation. It also includes an AI chat interface that enables users to understand how different API endpoints can help address their specific use cases. This approach is more efficient than manually reviewing the entire documentation.

Lastly, you can test the API endpoints from the UI. When you make authenticated API requests, the UI caches authentication tokens so that you don't have to type or paste them for subsequent requests.

Markdown Support

zod-to-openapi and Scalar have Markdown support. With Markdown, you can include conceptual documentation and more information about API endpoints that are not supported by the default documentation components like headers and the request body.

You can embed images, include tables and format text in the documentation. You can use Markdown to include notes that explain concepts related to the API.

How to Create the API Documentation

In this section, you will create an Express CRUD API project that uses zod-to-openapi and Scalar to document its APIs. To practice along, clone the Express starter project from GitHub at orimdominic/freeCodeCamp-zod-to-openapi-scalar.

Set up the Project

After cloning the project:

• install its dependencies using your preferred Node.js package manager

• start the server using the serve script

# Install dependencies
npm install

# Start the application
npm run serve

You should see the following output on the terminal if the application runs successfully:

> freecodecamp-zod-to-openapi-scalar@1.0.0 serve
> node --experimental-strip-types --watch src/index.ts

Listening on :3000

The project has two modules - Users and Pets.

The router configuration for each module is defined in the router.ts file, while the route controllers are located in the controllers.ts file within each module's folder under src/modules. The controllers do not contain business logic, they simply respond with JSON values generated by the Faker library.

How to Set Up zod-to-openapi

Install asteasolutions/zod-to-openapi using your preferred Node.js package manager. If you use npm, run the code snippet below in your terminal:

npm install @asteasolutions/zod-to-openapi

After the installation, create a folder called lib (library) in the src folder. In the lib folder, create a file called openapi.ts. The file will house the code that sets up zod-to-openapi for collating the API documentation and generating the OpenAPI specification.

Copy and paste the code snippet below into src/lib/openapi.ts:

import z from "zod";
import {
  extendZodWithOpenApi,
  OpenApiGeneratorV31,
  OpenAPIRegistry,
} from "@asteasolutions/zod-to-openapi";

extendZodWithOpenApi(z);

export const registry = new OpenAPIRegistry();

export const bearerAuth = registry.registerComponent("securitySchemes", "bearerAuth", {
  type: "http",
  scheme: "bearer",
  bearerFormat: "JWT",
});

export function generateOpenAPIDocument() {
  const generator = new OpenApiGeneratorV3(registry.definitions);

  return generator.generateDocument({
    openapi: "3.1.0",
    info: {
      title: "Users API",
      version: "1.0.0",
      description: `Backend API documentation for users application.`,
    },
    tags: [
      {
        name: "users",
        description: "For operations carried out by admin users",
      },
    ],
    servers: [
      {
        url: "http://localhost:3000",
        description: "Local server",
      },
    ],
  });
}

zod-to-openapi v8 requires zod v4. If you use zod v3, you should use v7.3.4 of zod-to-openapi.

extendZodWithOpenApi is a method provided by zod-to-openapi that enhances Zod schemas by adding an openapi method. The openapi method allows you to attach additional documentation to request payloads, responses, parameters, and their properties, which are then displayed in the API documentation rendered by Scalar.

It is important to call extendZodWithOpenApi before loading any files that use the openapi method, otherwise accessing openapi on Zod objects will result in errors.

An alternative is to use the meta method on zod v4 schemas for the additional documentation. For example, schemaOne and schemaTwo in the code snippet below are the same:

const schemaOne = z
  .string()
  .openapi({ description: 'Name of the user', example: 'Test' });

const schemaTwo = z
  .string()
  .meta({description: 'Name of the user', example: 'Test' });

The meta method supports all metadata information that you'd normally pass to openapi and will produce exactly the same results.

The OpenAPIRegistry is a utility that is used to collate API documentation which would later be passed to an OpenAPI specification generator. registry is created from OpenAPIRegistry, exported, and used to document API endpoints and components in modules where it is imported.

export const registry = new OpenAPIRegistry();

bearerAuth is a component created by the registry to represent JWT authentication. When bearerAuth is included in the documentation of an endpoint, the UI renders an input for submitting an authentication token for authenticated requests as shown in the image below.

In the registerComponent method, "securitySchemes" registers a security scheme component. "bearerAuth" , the first argument of registerComponent, is the name given to the component and it can be changed to a name that you prefer. It appears in the top right of the authentication token input, shown in the image above. The third input to registerComponent is an object that defines the component.

When generateOpenAPIDocument function is executed, it collates all the registry API definitions in the project, generates the OpenAPI specification through generator.generateDocument, and returns the specification as JSON.

The tags property in generator.generateDocument organizes API endpoints into sections on the documentation UI. For example, all API endpoints with the Users tag in their registry definition will be placed under the Users section of the UI. description can be written in Markdown within template literals.

The servers property is a collection of the servers connected to the application. If you have multiple servers, you have the option of selecting what server to use for the base URL in the documentation UI for making API requests from it.

With this setup in place, when endpoints are documented with the registry, generateOpenAPIDocument will have an OpenAPI specification to return.

How to Generate the Documentation UI with Scalar

In this section, you will set up Scalar and connect it to the return value of generateOpenAPIDocument. You will also connect Scalar with an Express route, allowing the application to serve the documentation UI at that route.

Scalar has an Express API reference library that makes it easier for you to connect it with the OpenAPI specification and Express. Install scalar/express-api-reference using your preferred Node.js package manager. If you use npm, use the snippet below:

npm install @scalar/express-api-reference 

Copy and paste the code snippet below into src/app.js:

import express from "express";
import router from "./router.ts";
import { generateOpenAPIDocument } from "./lib/openapi.ts";
import { apiReference } from "@scalar/express-api-reference";

const app = express();
app.use(express.json(), express.urlencoded({ extended: true }));

app.get("/", function (req, res) {
  return res.send("OK");
});

app.use("/api", router);

const apiDocJsonContent = generateOpenAPIDocument();

app.use(
  "/docs", // documentation route
  apiReference({
    content: apiDocJsonContent,
    title: "Users API",
    pageTitle: "Users API",
  }),
);

export default app;

In the code snippet above, generateOpenAPIDocument is imported from src/lib/openapi.ts, and apiReference is imported from @scalar/express-api-reference. When executed, generateOpenAPIDocument returns the OpenAPI specification, which is stored in apiDocJsonContent for caching to improve perfoemance.

A GET /docs route is then created, with the Scalar apiReference function acting as the controller. It accepts apiDocJsonContent and returns a web page whenever the GET /docs route is accessed.

With this setup in place, run the application using npm run serve and visit the documentation page at http://localhost:3000/docs in your browser. You should see a user interface similar to the image below:

To view the codebase at this point, run git checkout set-up-openapi-scalar .

Document the Endpoints

You have set up zod-to-openapi and connected it with Scalar. You have also hooked it up with a route in the backend application. In this section, you will write code to document the endpoints in the application for generating the OpenAPI specification and rendering it on the documentation UI.

To document the route for creating users ( POST /api/users ), in src/modules/users/router.ts , import registry, the schemas and zod using the snippet below:

import z from "zod";
import { registry } from "../../lib/openapi.ts";
import { 
    UserSchema, 
    UserListItemSchema,
    UpdateUserSchema, 
    CreateUserSchema, 
} from "./types.ts";

Copy and paste the code below above the create user route to document the create user endpoint:

registry.registerPath({
  method: "post",
  path: "/api/users",
  summary: "Create user",
  tags: ["users"],
  request: {
    body: {
      content: {
        "application/json": {
          schema: CreateUserSchema,
        },
      },
      description: "Create user payload",
      required: true,
    },
  },
  responses: {
    201: {
      description: "User created",
      content: {
        "application/json": {
          schema: z.object({
            message: z.string().openapi({ example: "User created" }),
            data: UserSchema,
          }),
        },
      },
    },
  },
});

Visit the documentation page and you will find see a web page similar to the image below:

The UI result of some of the input fields of registry.registerPath have been labelled in the image above. The description in the API endpoint is italicised because its value is Markdown in a template string.

By registering the route path for creating users with registry.registerPath and filling its values, you added the documentation of the route to the registry definitions and that makes it included in the OpenAPI specification.

To test the endpoint from the documentation UI:

• click the Test Request button

• fill in the payload in the dialog that appears and

• click the Send button

To document the get user by id route (GET /api/users/:id ), import bearerAuth from src/lib/openapi.ts, copy the code snippet below and paste it above the get user by id route definition.

registry.registerPath({
  method: "get",
  path: "/api/users/{userId}",
  summary: "Get user details by id",
  tags: ["Users"],
  security: [{ [bearerAuth.name]: [] }],
  request: {
    params: z.object({ userId: z.int() }),
  },
  responses: {
    200: {
      description: "User retrieved",
      content: { "application/json": { schema: UserSchema } },
    },
  },
});

When the request.params field is defined using a Zod object, it generates an input UI on the documentation web page that enables users to provide values for path parameters such as userId, highlighted in the image below:

The complete code for the documentation of all endpoints in this section can be accessed when you check out the complete-project branch by running git checkout complete-project in your terminal. It contains documentation for the endpoint for uploading user photo, which demonstrates how to document endpoints that accept file uploads.

How to Use Scalar with NestJS

Scalar has a library that integrates with NestJS. You can use supply the Swagger document created by swagger/nestjs to the Scalar NestJS integration library to generate the Scalar documentation UI.

In root folder of your NestJS project, install the Scalar NestJS integration library:

npm install @scalar/nestjs-api-reference

Update the main.ts file of your NestJS project with the code snippet below:

import { NestFactory } from '@nestjs/core';
import { apiReference } from '@scalar/nestjs-api-reference';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .addBearerAuth()
    .build();

  const openApiSpecification = SwaggerModule.createDocument(app, options);
  
  // integrate the documentation with NestJS
  app.use(
    '/api/docs', // documentation route
    apiReference({
      content: openApiSpecification,
    }),
  )

  await app.listen(3000);
  console.log(`Application is running on: ${await app.getUrl()}`);
}

bootstrap();

With this setup in place, you can visit the /api/docs route in your browser to view the Scalar documentation for your NestJS application.

How to Resolve Content Security Policy (CSP) Errors When Used with Helmet

If you use Helmet in your Express or NestJS project, you will encounter CSP errors when you try to render the Scalar documentation UI. To resolve the errors, update the Helmet CSP configuration in your code to have the value of the object in the code snippet below:

{
    directives: {
      defaultSrc: [`'self'`],
      styleSrc: [`'self'`, `'unsafe-inline'`],
      imgSrc: [`'self'`, 'data:', 'validator.swagger.io'],
      scriptSrc: ['self', 'https:', 'unsafe-inline'],
    },
  }

Absence of AsyncAPI Documentation Feature

At the time of writing, Scalar does not fully support rendering AsyncAPI specifications for event-driven architecture APIs, although it is currently under development. You can track the progress of its development through the GitHub issue linked in the documentation to stay informed about its release.

Conclusion

You have learned about zod-to-openapi and how it makes it easier for you to generate an OpenAPI specification for your REST APIs than writing comments or large YAML files. You also learned how to use the specification document generated to render a beautiful API documentation UI which also functions as a lightweight API client. Endeavour to implement it in your projects that need a documentation uplift.

Feel free to connect with me on LinkedIn for questions or clarifications. Thank you for reading this far and I hope this helps you achieve what you intended to achieve. Don’t hesitate to share this article if you feel that it would help someone else out there. Cheers!

Caching is great for performance, but it becomes a pain when you don’t realize which layer is reusing old data.

If you’ve ever seen this:

• You update a profile name, but the screen still shows the old one.

• You delete an item, but it stays in the list.

• Your API returns fresh JSON, but the page refuses to change.

• You deploy a fix, but your teammate still sees the old behavior.

You’re probably hitting a cache.

What makes this especially confusing is that not all stale UI comes from “real” caches. Modern web apps have multiple places where data can be reused, saved, or replayed between your UI, your API and when your app is deployed. When you don’t have a clear mental model of these layers, debugging turns into guesswork.

This article lays out a practical guide of the five most common caching layers that cause stale UI, plus one non-cache trap that looks exactly like one. The goal is to help you quickly identify where stale data is coming from, so you can fix the right thing instead of “refreshing harder.”

Why it Matters

I first ran into this while building an app where the UI wouldn’t update after a successful change. The API returned 200 OK, the database was correct, but the screen stayed stale. I assumed something was wrong with my code or state logic. Instead, the issue was coming from a caching layer I hadn’t invalidated. That’s the real problem with stale UI, you can’t debug it effectively unless you know which layer might be serving cached data.

When you understand where caching happens:

• You debug faster by identifying the layer instead of guessing.

• You avoid production-only bugs caused by caching defaults.

• You stop chasing React issues when the data was never fresh.

This article gives you a simple mental model to pinpoint the layer and fix the right thing.

Table of Contents

• Why it Matters

• The Mental Model

• Non-Cache Cause

• Cache 1: React Query Cache

• Cache 2: Next.js fetch() Caching

• Cache 3: Browser HTTP Cache (a Saved Copy in Your Browser)

• Cache 4: CDN/Hosting Cache

• Cache 5: Service Worker Cache (Only if Your Site is a PWA)

• 10-Second Debug Guide

• Prevention: Set Caching Intentionally

• Recap

The Mental Model

When your UI shows data, it feels like it comes straight from your API. In reality, the request/response path can hit multiple reuse points.

Non-Cache Cause

Duplicated React local state (same symptoms as caching). This one isn’t a formal cache, but it causes a lot of “why didn’t it update?” bugs especially for beginners.

The common trap:

const [name, setName] = useState(user.name) // initialized once

useState only uses its argument during the initial render. On every subsequent render, React ignores this value and preserves the existing state.

If user.name later changes (for example, after fresh API data arrives), the name state will not update automatically. At that point, name becomes a stale copy of user.name, and the UI renders outdated data unless you manually synchronize it.

This happens because you have duplicated state:

• user.name is the source of truth.

• name state is a local snapshot taken once.

React does not keep duplicated state in sync for you.

Correct patterns:

1. Render directly from the source when possible.

If the value is not being edited locally, do not copy it into state:

<span>{user.name}</span>

This guarantees the UI always reflects the latest data.

2. Explicitly synchronize local state when editable state is required.

If you need local, editable state (for example, a controlled input), you must opt in to synchronization:

const [name, setName] = useState(user.name);  

    useEffect(() => {    
        setName(user.name); 
     }, [user.name]);

This effect runs only when user.name changes, explicitly updating local state to match the new source value.

Cache 1: React Query Cache

React Query (TanStack Query) stores query results in a QueryClient cache (in memory by default) so your UI can render quickly and avoid unnecessary network requests. When a component needs data, React Query can return cached data immediately and then decide whether to fetch the data again based on options like staleTime and “refetch” behaviors (on mount, window focus, reconnect).

Common failure mode: mutation succeeds, but the UI stays old

A 200 OK only confirms the mutation request succeeded. It does not automatically update the cached query data your UI is rendering.

After a mutation, one of these usually happens:

• The query that renders the screen was not invalidated/fetched

• You invalidated the wrong query key (the UI reads from a different key)

• The UI is rendering local React state that’s out of sync (not the query result)

The simplest “safe” pattern is: invalidate the exact query key your UI uses, so it fetches fresh data.

import { useMutation, useQueryClient } from "@tanstack/react-query";

function useUpdateProfile(userId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updateProfileRequest,
    onSuccess: () => {
      // Invalidate the same key your UI query uses (example: ["user", userId])
      queryClient.invalidateQueries({ queryKey: ["user", userId] });
    },
  });
}

If your UI uses a different key (for example ["me"] or ["user", userId, "profile"]), you must invalidate that key instead, React Query won’t “figure it out” from the URL.

Query Keys: React Query Caches by Key, not URL

React Query does not cache by endpoint URL. The query key is the identity of the cached data. If two different requests share the same key, React Query treats them as the same data and they can overwrite each other.

You should avoid keys like ["user"] (too broad), and use keys like ["user", userId] and ["users", { page, search, filter }].

Two settings that control “when it will refetch”:

• staleTime: how long cached data is treated as fresh. While data is fresh, React Query is less likely to refetch automatically.

• gcTime (formerly cacheTime): how long unused query data stays in memory after it’s no longer used by any component, before it’s garbage collected.

Cache 2: Next.js fetch() Caching

This is the one that surprises a lot of frontend devs. Next.js can cache results to speed things up. That means your server might return a previously saved copy of:

• The API data it fetched, or

• The page it already built

This is often the first time frontend developers encounter server-side caching behavior that affects UI correctness. So, even if your database has the new value, you can still see the old one, because Next.js didn’t fetch the API again, or didn’t rebuild the page this time.

This mainly applies to the App Router (Next.js calls these saved copies the Data Cache and Full Route Cache).

What you’ll notice when this happens

• You refresh the page and it still shows the old value.

• Your API is correct (Postman/curl shows the new email), but the UI is stuck.

• Sometimes it “fixes itself” after a short wait (because the saved copy refreshes on a timer).

For example: “I updated my profile email, but prod still shows the old one”

The page (reads email on the server):

// app/settings/page.tsx
export default async function SettingsPage() {
 const res = await fetch("https://api.example.com/users/42", {
  method: "GET",
})
  const user = await res.json();

  return (
    <main>
      <h1>Settings</h1>
      <p>Email: {user.email}</p>
    </main>
  );
}

You submit an “Update email” form, the API returns 200 OK, the database is updated, but /settings still shows the previous email in production.

That usually means you’re seeing a saved copy somewhere on the server side.

How to debug it

Step 1: Reproduce in a production-like run

Caching can behave differently in development. Run:

next build && next start

Then test again.

Step 2: Confirm whether the request is reaching your Next.js server at all

Add a log inside the page:

console.log("Rendering /settings at", new Date().toISOString());

Then reload settings twice.

• If you see a new timestamp every reload, the request is reaching your server and the page code is running.

• If you don’t see logs in production, your request may not be reaching your server at all (often because a hosting/CDN layer is serving a saved copy before Next.js runs). You’ll confirm that in the CDN section later.

Step 3: Force Next.js to ask your API every time

Change the fetch to:

const res = await fetch("https://api.example.com/me", {
  method: "GET",
  cache: "no-store",
});

This means: don’t save this response – always fetch it again.

If this fixes the stale email then the problem was a saved copy of the API response (Data Cache).

Step 4: If the email is still stale, force Next.js to rebuild the page every request

Add this to the page file:

// app/settings/page.tsx
export const dynamic = "force-dynamic";

This means: don’t serve a saved copy of the page; rebuild it per request.

A “beginner-safe” setup for the user settings pages with some of the suggestions:

// app/settings/page.tsx
export const dynamic = "force-dynamic";

export default async function SettingsPage() {
  const res = await fetch("https://api.example.com/me", { cache: "no-store" });
  const me = await res.json();
  return <p>Email: {me.email}</p>;
}

When you want caching for speed, but still need real time updates, these are some options you can take:

Option A: Refresh the saved copy every N seconds

Good for public pages, not ideal for “my settings must update now.”

await fetch(url, { next: { revalidate: 60 } });

This means: “You can reuse a saved copy, but refresh it at most every 60 seconds.”

Option B: Refresh right after the update (best for “update email” flows)

If you update the email on the server (Server Action or API route), tell Next.js to throw away the saved copy for /settings page so the next visit is fresh:

// app/settings/actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function updateEmail(email: string) {
  await fetch("https://api.example.com/me/email", {
    method: "PUT",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ email }),
  });

  // Tell Next.js: next request to /settings should be rebuilt
  revalidatePath("/settings");
}

Note: Next.js caching details can differ by version and by App Router vs Pages Router. Instead of trying to memorize defaults, debug by setting the behavior explicitly (no-store, revalidate, force-dynamic) and observe what changes.

Cache 3: Browser HTTP Cache (a Saved Copy in Your Browser)

Sometimes the browser reuses a saved copy of an API response (from memory or disk), so it doesn’t fully fetch it again.

What you’ll notice

You open DevTools, and the network shows (from memory cache) or (from disk cache).

Fast check

DevTools → Network

• Turn on Disable cache (only works while DevTools is open)

• Reload and retry

Why it happens

Usually your server allows caching via headers like Cache-Control or ETag (which can lead to 304 Not Modified).

Cache 4: CDN/Hosting Cache

This is often a production-only cache, which is why frontend bugs can appear “impossible” to reproduce locally. In production, a CDN/hosting layer can serve a saved copy of a response before your request reaches your server. That’s why “prod is stale, local is fine” happens.

What you’ll notice

• Prod is stale, local is fine

• Different users see different results (different regions/POPs)

• Pages are very fast even right after data changed

Fast check

Open DevTools → Network → click the request → Response Headers

• Age: if present and increasing, it’s strong evidence you’re getting a cached response from an intermediary cache

• Provider headers can hint HIT/MISS (examples: x-vercel-cache, cf-cache-status)

• Source (Age header, HTTP caching): https://www.rfc-editor.org/rfc/rfc9111

Quick diagnostic check

Change the URL slightly by adding this to the end of the URL:

?debug=1700000000000

If the new URL shows fresh data, the edge was likely caching the original URL. This doesn’t fix it for everyone, you’d still need correct cache settings or a purge/invalidation on your CDN.

Cache 5: Service Worker Cache (Only if Your Site is a PWA)

If your site has a service worker, it can return a saved response before the network runs. This can make new deployments or new data seem “ignored.”

What you’ll notice

• Works in Incognito but not normal mode

• Hard refresh doesn’t help

• DevTools “Disable cache” doesn’t fully explain it

Fast check (Chrome)

Open DevTools → Application → Service Workers

• enable Bypass for network, or Unregister temporarily

• reload and retest

10-Second Debug Guide

Stale data is rarely random: it usually means a cache layer is doing its job, just not in the way you expect. Modern applications stack multiple caches, so debugging is less about fixing code immediately and more about locating the layer responsible.

Think of this as a quick cheat sheet to figure out which cache layer might be serving stale data, so you can focus your debugging on the right layer.

• No request in Network? Go to Cache 1 (React Query), then Local state, then Cache 5 (Service worker).

• Request exists, but response is old? Go to Cache 3 (Browser), Cache 4 (CDN), then Cache 2 (Next.js).

• Response is fresh, UI is old? Go back to Cache 1 (invalidating / query keys) and Local state.

Once you know the likely layer, use the Fast check in that section to confirm it.

Prevention: Set Caching Intentionally

Most stale-data bugs happen because caching settings were never chosen but the defaults were.

• User-specific pages (settings/admin/dashboard): default to fresh: Next.js: use cache: "no-store" on important fetches, and/or force dynamic routes when needed.

• Public pages (marketing/blog/docs): saving + revalidate is usually fine: Decide a revalidate window that matches the business need (seconds/minutes/hours).

• React Query: set staleTime based on how often the data actually changes, and make query keys match the inputs.

• APIs: set Cache-Control / Vary intentionally so shared caches don’t mix user-specific responses.

Recap

Caching itself isn’t the problem. Stale UI happens when a cache exists but you didn’t choose it intentionally or align it with the data’s freshness requirements.

If the UI won’t update, it’s usually because you’re seeing a saved copy from React Query, Next.js, the browser, a CDN, or a service worker. And sometimes it’s not a cache at all, it’s local React state

To resolve this issue in the past, you typically had to create a multitude of TypeScript interfaces by hand, using GraphQL Code Generator to generate the interface files, or hope that it all worked out. Well, there’s a better way to accomplish this now, without the need for code generation.

tRPC and Hono are two applications that are changing how we develop TypeScript-based applications throughout the entirety of the full-stack.

By the end of this tutorial, you’ll understand:

• Why traditional REST APIs fail at type safety

• How tRPC provides full end-to-end type inference between backend and frontend

• How Hono delivers type-safe APIs while staying REST-friendly

• When to choose tRPC vs Hono for your projects

• How these tools improve developer experience, team velocity, and reliability

If you’re building full-stack TypeScript applications and want fewer runtime bugs and faster iteration, this guide is for you.

Table of Contents

• Prerequisites

• The Problem with Traditional APIs

• What Makes tRPC Different?

• Hono: The Lightweight Challenger

• Why This Matters These Days

• Getting Started

• The Future is Type-Safe

Prerequisites

To follow along comfortably, you should have:

• Basic knowledge of TypeScript

• Familiarity with REST APIs and how frontend-backend communication works

• Some experience with Node.js and modern JavaScript frameworks

• A general understanding of frontend frameworks like React or Next.js (helpful, but not required)

You don’t need prior experience with tRPC, Hono, or GraphQL.

The Problem with Traditional APIs

You’ve probably written something like this a hundred times:

// Backend (Express)
app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  // Do stuff with user
  res.json({ id: 1, name, email });
});

// Frontend
const createUser = async (name: string, email: string) => {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, email })
  });
  return response.json(); 
};

The backend knows the shape of the data. But the frontend...it hopes it gets it right. You end up writing interfaces manually, like:

interface User {
  id: number;
  name: string;
  email: string;
}

If you change the backend tomorrow to return userId instead of id, TypeScript won't catch it. Your types and reality have diverged, and you won't know until runtime.

GraphQL tried to solve this with schemas and codegen, but honestly? Setting up GraphQL feels like assembling IKEA furniture without instructions. You need a schema, resolvers, code generation tools, and suddenly your "simple" API has a 30-minute setup process.

What Makes tRPC Different?

tRPC flips the script entirely. Instead of defining your API in a separate schema language, your TypeScript code is the schema. Here's the same API in tRPC:

// Backend (tRPC router)
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const appRouter = t.router({
  createUser: t.procedure
    .input(z.object({
      name: z.string(),
      email: z.string().email(),
    }))
    .mutation(({ input }) => {
      // Do stuff with user
      return { id: 1, name: input.name, email: input.email };
    }),
});

export type AppRouter = typeof appRouter;

This is where it gets cool. On your frontend:

// Frontend - fully type-safe!
import { createTRPCClient } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  url: 'http://localhost:3000/trpc',
});

// TypeScript knows EVERYTHING about this call
const user = await client.createUser.mutate({
  name: 'Alice',
  email: 'alice@example.com'
});

// user is automatically typed as { id: number; name: string; email: string; }

No code generation or build step, or GraphQL schema. Just pure TypeScript inference doing its thing. If you rename id to userId in your backend, your frontend will immediately show a TypeScript error. You'll catch it before you even save the file.

This is what we call end-to-end type safety, and it's honestly a great transition.

Hono: The Lightweight Challenger

While tRPC is amazing for full-stack TypeScript apps where you control both ends, Hono takes a slightly different approach. It's a lightweight web framework that gives you type safety while still being a traditional HTTP framework.

Here's the same example in Hono:

import { Hono } from 'hono';
import { z } from 'zod';
import { zValidator } from '@hono/zod-validator';

const app = new Hono();

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

app.post('/api/users', zValidator('json', userSchema), (c) => {
  const { name, email } = c.req.valid('json');
  return c.json({ id: 1, name, email });
});

export type AppType = typeof app;

On the frontend, you can use Hono’s RPC client:

import { hc } from 'hono/client';
import type { AppType } from './server';

const client = hc<AppType>('http://localhost:3000');

const response = await client.api.users.$post({
  json: { name: 'Bob', email: 'bob@example.com' }
});

const user = await response.json();
// user is fully typed!

Hono is incredibly fast (it runs on Cloudflare Workers, Deno, Bun, and Node.js), and it gives you that sweet type safety while still being a "regular" HTTP framework. You get RESTful routes, middleware, and all the familiar patterns – just with TypeScript powers.

Why This Matters These Days

You might think to yourself, “Okay, I know what you mean, but why should I care about it?” There’s a reason why these tools are being utilized more now than ever before.

Developer experience is essential

In 2026 and beyond, we’ll no longer accept long feedback loops. The ability to modify your backend code and see what might break on your frontend application without having to run the application will be fantastic for productivity. We’ll spend less time fixing bugs and more time creating new functionalities.

Smaller teams, better apps

With tRPC or Hono, one developer can create an entire full-stack application with type safety at a very fast pace because they don’t have to switch back and forth between REST documentation and TypeScript interfaces – all the data is flowing to and from their backend code directly to their frontend.

The end of “Works on my machine“

With type safety, errors are caught at compile time instead of at the time your end-user clicks on a button. This is especially impactful when working in larger teams, when the backend developers and front-end developers may not be in constant communication with one another.

Getting Started

Want to try this out? Here's the fastest way:

For tRPC:

npm create @trpc/next-app@latest

This scaffolds a Next.js app with tRPC already configured. Check out the official tRPC docs for more.

For Hono:

npm create hono@latest

Pick your runtime (Node.js, Cloudflare Workers, etc.), and you're off to the races. The Hono documentation is excellent and super approachable.

The Future is Type-Safe

Look, REST isn't going anywhere, and GraphQL has its place. But for full-stack TypeScript developers, tRPC and Hono represent something special: type safety without the ceremony. No code generation or no schema duplication, just TypeScript doing what it does best.

In the future, when you start a new project, give one of these a shot. Your future self – the one who's refactoring code at 2 AM – will thank you.

Happy coding!

Many store features you see every day, such as discounts, bundles, and order fulfillment are built using apps. These apps are created by developers to extend Shopify and solve real problems for merchants.

If you know JavaScript and basic web development, you already have enough skills to start building Shopify apps.

In this tutorial, you’ll learn what a Shopify app is, how Shopify apps work, and how to set up your development environment. You’ll also see three real examples of popular Shopify apps and how they are built.

What We’ll Cover

• What Is a Shopify App?

• How Shopify Apps Work

• Setting Up Your Development Environment

• Understanding Shopify APIs

• Case Study One: Bundle and Discount Apps

• Case Study Two: Printful and Order Fulfilment

• Case Study Three: Shiprocket and Shipping Rates

• Testing Your Shopify App

• Preparing for the Shopify App Store

• Conclusion

To follow this tutorial, you should be comfortable with JavaScript and APIs. Some experience with Node.js and npm will help, but you do not need to be an expert. No prior experience with Shopify is required.

What Is a Shopify App?

A Shopify app is a web application that connects to a Shopify store. The app runs on your own server or a serverless platform.

It talks to Shopify using secure APIs. When a merchant installs your app, they allow it to access certain store data. This could include products, orders, or customers, depending on the permissions given.

There are different types of Shopify apps.

Public apps are listed on the Shopify App Store and can be installed by any merchant. These apps must pass a review before approval.

Custom apps are built for a single store, and private apps are used only inside a company.

Most Shopify apps include backend code that calls Shopify APIs, a frontend interface shown inside the Shopify Admin, storefront features that shoppers can see, and webhooks that react to store events.

How Shopify Apps Work

When a merchant installs your app, Shopify starts an OAuth process. This is a secure way to ask the merchant for permission.

Once approved, Shopify sends your app an access token. This token allows your app to make API calls to the store.

Shopify apps can add screens inside the admin area using App Bridge and Polaris. These tools make your app feel like part of Shopify. Apps can also add features to the storefront using theme app extensions.

Shopify provides both REST and GraphQL APIs. REST is easy to use, but GraphQL is faster and more efficient. Today, most new apps use GraphQL.

Setting Up Your Development Environment

Before you start coding, you’ll need a few tools. You’ll need to install Node.js and the Shopify CLI. You’ll also need a Shopify Partner account. The Partner account lets you create apps and test them without cost.

The Shopify CLI helps you create a starter app quickly. You can generate a working app by running these commands:

shopify app create node
cd my-shopify-app
npm install
shopify app serve

This creates an app with login, authentication, and an embedded admin interface. It also sets up a secure tunnel so Shopify can reach your local server while you develop.

Understanding Shopify APIs

Shopify provides APIs for almost every part of a store. This includes products, orders, customers, and shipping. Your app can only access data that the merchant has allowed during installation.

Here’s a simple example of fetching products using the GraphQL Admin API:

import fetch from "node-fetch";

async function getProducts(shop, token) {
  const query = `
  {
    products(first: 5) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
  `;
  const response = await fetch(
    `https://${shop}/admin/api/2025-10/graphql.json`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Access-Token": token
      },
      body: JSON.stringify({ query })
    }
  );
  const data = await response.json();
  return data.data.products.edges;
}

This function gets the first five products from a store. The access token comes from the OAuth process during app installation.

Case Study One: Bundle and Discount Apps

Bundle and discount apps help merchants offer deals like “Buy two, get ten percent off.” These apps must work with Shopify’s pricing rules and checkout system. A popular example is the Bundle Deals app, which shows offers on product and cart pages.

These apps usually add small UI elements to the storefront using theme app extensions. They use Shopify’s Discount APIs to apply offers safely.

They don’t change checkout directly. Instead, they enhance the storefront and let Shopify handle the final pricing.

A storefront script might look like this:

fetch("/apps/bundle-deals/api/bundles?productId=gid://shopify/Product/123")
  .then((res) => res.json())
  .then((bundles) => {
    displayBundles(bundles);
  });

This code runs in the store’s frontend. It fetches bundle rules from your app server and shows them to shoppers.

Case Study Two: Printful and Order Fulfilment

Printful is a popular app that connects Shopify stores with a print-on-demand service (for example, T-shirts, Mugs, and so on). When a customer places an order, Printful receives the order and starts production.

Apps like this need access to orders and reliable event handling. They use webhooks to listen for new orders. When Shopify sends a webhook, the app forwards the data to an external system.

Here is a simple webhook example:

app.post("/webhooks/orders/create", async (req, res) => {
  const order = req.body;

await printfulClient.createOrder({
    external_id: order.id,
    items: order.line_items.map(item => ({
      variant_id: item.variant_id,
      quantity: item.quantity
    }))
  });
  res.status(200).send("Order processed");
});

This keeps Shopify and Printful in sync. The same pattern is used for shipping tools, accounting software, and CRMs.

Case Study Three: Shiprocket and Shipping Rates

Shiprocket helps merchants manage shipping and delivery. Shipping apps often calculate rates in real time and update order status after shipment.

Since Shopify restricts what can run during checkout, shipping apps typically calculate rates before checkout begins or use carrier service APIs. A simple rate endpoint might look like this:

app.post("/shipping/rates", async (req, res) => {
  const { destination, items } = req.body;
  const rates = await fetchCarrierRates(destination, items);

res.json({
    rates: rates.map(rate => ({
      service_name: rate.name,
      total_price: rate.price
    }))
  });
});

This lets merchants show shipping options to customers before they reach checkout.

Testing Your Shopify App

Testing is a critical part of building a reliable Shopify app, especially if you plan to submit it to the App Store. Every feature should be tested thoroughly in a development store before you consider a release. A development store lets you simulate real merchant behavior without affecting live data, which makes it ideal for both manual and automated testing.

In addition to live testing, Shopify allows you to mock API responses during development. Mocking lets you test your business logic without relying on real API calls or rate limits. This is especially useful when simulating error scenarios or incomplete data, such as missing fields or unexpected values.

By combining real store testing with mocked responses, you can be confident that your app behaves correctly in both normal and failure conditions.

Preparing for the Shopify App Store

Preparing for the Shopify App Store is an important step if you want to release a public app that merchants can trust and install with confidence. Shopify has a formal review process, and your app must meet both technical and policy requirements before it can be listed.

Your app should request only the API permissions that are absolutely necessary for its core functionality. Asking for extra or unrelated permissions is one of the most common reasons apps get rejected. Shopify expects you to clearly explain why each permission is needed and how the data will be used. This helps merchants feel safe when installing your app.

You must also include basic legal and support information. This includes a clear privacy policy that explains what data you collect and how you handle it, terms of service that define usage rules, and a visible support contact such as an email address or help page.

Finally, Shopify looks closely at app quality. Your app should be stable, handle errors gracefully, and be tested across common store scenarios. Clear messaging, predictable behavior, and transparent data usage go a long way in passing the review process.

Conclusion

Building your first Shopify app takes time, but it’s very achievable. Start with login and API calls. Learn how to embed UI inside Shopify. Study real apps from the Shopify app store. Each one solves a different problem using a different design.

As you practice, the pieces will start to fit together. Keep building, testing, and reading the documentation. Your first Shopify app could be the start of something much bigger.

At first, they might look the same. Both allow one piece of software to ask another for data or perform an action. But the way they work and the reason they exist are completely different.

An API, or Application Programming Interface, is built for developers. It’s how one program communicates with another. MCP, or Model Context Protocol, is built for AI models. It’s how a large language model like GPT or Claude can safely talk to external systems and use tools.

Let’s look at what makes them different, why MCP exists when APIs already do the job, and how they work in real examples.

Table of Contents

• What is an API?

• What is MCP?

• How MCP Works

• Why Not Just Use an API?

• MCP vs API in Practice

• Key Conceptual Difference

• Discovery and Schema

• Security and Privacy

• The Future of MCP

• Conclusion

What is an API?

An API is a set of rules that lets software talk to software.

It is like a waiter in a restaurant. You tell the waiter what you want, the kitchen prepares it, and the waiter brings it back. You never go into the kitchen yourself.

For example, if you want to get details of a GitHub user, you can make a simple API request.

GET https://api.github.com/users/username

The server replies with a response like this:

{
  "login": "john",
  "id": 12345,
  "followers": 120,
  "repos": 42
}

The API follows a pattern that both the client and the server understand. Developers use APIs every day to connect systems like payment gateways, weather data, or user accounts.

APIs are built for humans to code against. A developer writes the logic, sends requests, handles errors, adds authentication, and decides what to do with the response.

What is MCP?

MCP stands for Model Context Protocol. It’s a new standard that allows AI models to interact with external tools, data, and systems in a safe, structured way.

MCP is not meant for developers directly. It’s meant for large language models.

An AI model cannot make network requests by itself. It doesn’t know how to use headers, tokens, or API formats. It just predicts text based on what you type.

So if you tell a model, “Get the weather for Delhi,” it might generate some text that looks like a Python request. But it cannot actually run that code.

That is where MCP comes in. MCP acts like a bridge between the AI model and the real world. It defines a set of “tools” that the model can use safely.

Each tool is described using a schema so that the model knows what the tool does, what inputs it takes, and what it returns.

How MCP Works

You can think of MCP as a server that runs in the background. It exposes tools that an AI model can call. Each tool is a small piece of code that performs an action.

For example, you can write a simple MCP server in Python like this:

from mcp.server.fastmcp import FastMCP
import requests

mcp = FastMCP(name="github-tools")
@mcp.tool()
def get_repos(username: str):
    """Fetch public repositories for a user"""
    url = f"https://api.github.com/users/{username}/repos"
    return requests.get(url).json()
mcp.run()

This server defines a single tool called get_repos. It takes a username and fetches their GitHub repositories using the GitHub API.

Now, if an AI model is connected to this MCP server, it can ask for “get_repos for user john” and receive the data. The model does not know or care about the actual URL, headers, or tokens. The MCP server handles that part.

Why Not Just Use an API?

You might wonder, why not just let the AI model call the API directly? If the model can talk to APIs, why add another layer?

The short answer is that AI models cannot safely call APIs on their own. They have no built-in execution environment, no way to store secrets, and no limits.

Letting a model make arbitrary network requests would be dangerous. It could expose keys, access private data, or even cause damage by mistake.

MCP solves that problem by creating a controlled layer between the model and your systems. You decide which tools the model can use. You can restrict inputs, filter outputs, and monitor everything the model does.

In an MCP setup, the model never sees API keys or sensitive URLs. It just calls a tool that you define. The tool itself handles the network call and returns only the safe data.

This makes MCP much safer for real-world use, especially in enterprise or private environments.

MCP vs API in Practice

Let’s take a simple example. Suppose you want an AI to fetch weather data.

If you were using an API, you might write code like this:

import requests
response = requests.get("https://api.weatherapi.com/v1/current.json?key=API_KEY&q=Delhi")
print(response.json())

That works fine if a human developer runs it. But if an AI model tried to do the same, it would need access to your API key, network, and code execution. That is unsafe.

With MCP, you can define a tool like this:

@mcp.tool()
def get_weather(city: str):
    """Get weather for a city"""
    import requests
    url = f"https://api.weatherapi.com/v1/current.json?key=API_KEY&q={city}"
    return requests.get(url).json()

Now the AI model can simply say, “Call get_weather with city=Delhi,” and the MCP server runs the function.

The model does not see the API key or the actual URL. It just uses the tool safely.

Key Conceptual Difference

The difference between MCP and API is not just technical. It’s also philosophical.

APIs are for humans to use directly. They assume the caller understands the system, can handle tokens, and knows how to format requests.

MCP is for AI models. It assumes the caller is an intelligent but untrusted system that cannot hold secrets or execute code. The protocol gives the model only what it needs to perform reasoning and tool usage.

So while APIs expose endpoints like /users or /weather, MCP exposes capabilities like “get_user_info” or “get_weather.” The AI model does not call URLs. It calls functions with typed parameters.

Discovery and Schema

Another big advantage of MCP is that it can tell the model what tools are available.

When an AI model connects to an MCP server, it can ask for a list of tools. The server replies with their names, descriptions, and parameters in a structured format.

For example, the model might receive something like this:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get weather for a city",
      "parameters": {
        "city": {"type": "string"}
      }
    }
  ]
}

This means the model does not need separate documentation or prompt tuning. It knows exactly how to call each tool.

In contrast, an API would require reading human-written docs, copying sample requests, and guessing formats.

Security and Privacy

MCP provides better control over what the model can do.

Since the tools are defined in your server, you can add rules, limits, and validations. You can prevent the model from sending dangerous inputs or accessing private data.

For example, your tool can reject requests that ask for too much data or contain suspicious patterns. You can also log every call for audit purposes.

APIs, on the other hand, are exposed over the internet. If an API key leaks or a model calls the wrong endpoint, you could face a data breach.

With MCP, everything can run locally, behind a firewall, or on a private network. The model never needs direct access to the outside world.

The Future of MCP

Big AI companies like OpenAI and Anthropic are adopting MCP as a shared standard. That means any model that supports MCP can use your tools without modification.

If you build a weather MCP server today, it could work with GPT, Claude, or any other MCP-compatible model in the future.

This makes MCP a unifying layer between AI systems and external tools, much like APIs are for web applications.

Conclusion

At a glance, MCP and APIs might seem similar because both pass data between systems. But the difference lies in for whom they are built.

APIs are built for developers and systems that can safely make network calls. MCP is built for AI models that reason with text but cannot safely execute code.

An API gives you endpoints to access data. MCP gives the AI tools to use that data safely.

Think of it this way. APIs connect machines. MCP connects intelligence to machines.

That is why MCP is not replacing APIs but sitting above them as a new layer. APIs will still provide the data. MCP will just make it possible for AI to use those APIs safely, with structure, control, and understanding.

Hope you enjoyed this article. Signup for my free AI newsletter TuringTalks.ai for more hands-on tutorials on AI. You can also find visit my website.

Websites come with ads, navigation bars, and messy HTML. Before your Large Language Model (LLM) can understand the content, you must clean and format it.

That’s where Firecrawl makes life easy. It’s an open-source API tool that turns any website into neat, structured data ready for LLMs in seconds.

In this tutorial, we’ll look at two ways of using Firecrawl. One is through Firecrawl’s API (a paid API with a free tier) and the other is a self-hosted version.

Table of Contents

• What Is Firecrawl?

• Why LLMs Need Clean Data

• Setting Up Firecrawl

• Scraping a Single Page

• Crawling an Entire Website

• Extracting Structured Data with AI

• Self-hosting Firecrawl using Sevalla

• Use Cases

• Conclusion

What Is Firecrawl?

Firecrawl is a web crawling and scraping service that helps developers collect clean data from websites. You give it a URL, and it returns the content in formats like Markdown, HTML, JSON, or even screenshots.

Unlike basic scrapers, Firecrawl understands complex websites that load content with JavaScript. It can crawl through links, follow pages, and handle the heavy lifting like proxies and anti-bot systems automatically.

In short, it does the hard part of web data collection, so you can focus on using that data for your AI or automation projects.

Why LLMs Need Clean Data

LLMs learn and respond based on the text you give them. If that text includes clutter like HTML tags, scripts, or irrelevant sections, the AI gets confused.

Clean, well-structured data helps the model stay focused on the real content, like the article body, product details, or documentation.

Firecrawl makes this process simple. Instead of spending hours building scrapers or cleaning text, you can get ready-to-use content in a single API call.

Setting Up Firecrawl

To get started, create an account on firecrawl.dev and grab your API key. Running Firecrawl on your machine includes setting up a server, Redis cache, and so on. So we’ll use the API key from firecrawl.dev to test the API.

We can also quickly test its capabilities in the UI of the website.

Let’s use https://freecodecamp.org as the domain to see if Firecrawl can return some results.

And yes, we can see several URLs scraped by Firecrawl.

Now let’s access Firecrawl using code. The free plan lets you scrape 500 pages, so its all we need to understand how it works.

You can use either the Python SDK, the Node.js SDK, or direct API requests with curl.

Here’s how you install the SDKs:

Python:

pip install firecrawl-py

Node.js:

npm install @mendable/firecrawl-js

Once installed, you just need to set your API key and you’re ready to crawl.

Scraping a Single Page

Let’s say you want to extract the main content from Firecrawl’s homepage. You can do this in just a few lines.

Python Example:

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

doc = firecrawl.scrape(
    "https://firecrawl.dev",
    formats=["markdown", "html"]
)

print(doc.markdown)

This script returns the cleaned version of the page in Markdown format, perfect for an LLM to read or analyze.

With this one command, you get the core text, free from HTML clutter.

Crawling an Entire Website

If you need data from multiple pages like a full documentation site, you can crawl the entire domain. Firecrawl finds all the links and scrapes them automatically.

Example API call:

curl -X POST https://api.firecrawl.dev/v2/crawl \
  -H 'Authorization: Bearer fc-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10,
    "scrapeOptions": {
      "formats": ["markdown", "html"]
    }
  }'

This starts a crawl job and returns a job ID. Once done, you can download all the scraped pages in clean, LLM-ready formats.

Extracting Structured Data with AI

One of Firecrawl’s best features is AI-powered extraction. You can ask Firecrawl to read a page and return structured data, like a product’s price, description, or reviews, in JSON format.

Example:

curl -X POST https://api.firecrawl.dev/v2/extract \
  -H 'Authorization: Bearer fc-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://firecrawl.dev/*"],
    "prompt": "Extract the company mission and whether it is open source.",
    "schema": {
      "type": "object",
      "properties": {
        "company_mission": { "type": "string" },
        "is_open_source": { "type": "boolean" }
      }
    }
  }'

Firecrawl uses a built-in LLM to read the content and fill in the structure automatically. You can even skip the schema and just provide a natural-language prompt, like:

“Extract all the pricing details and feature names from this page.”

This is ideal for AI pipelines, RAG (Retrieval-Augmented Generation) systems, or dashboards that rely on clean, structured data.

Self-hosting Firecrawl using Sevalla

Firecrawl is open source, which means you don’t have to pay for the API if you prefer full control. You can deploy it on your own server and customise it however you like.

You can install Firecrawl on your local machine by setting up a database, cache, and other required components. But this setup will only work for local projects and won’t allow you to build or deploy applications that use Firecrawl.

To install Firecrawl, you can choose any cloud provider like AWS, Heroku, or others to setup this project. But I will be using Sevalla.

Sevalla is a modern, usage-based Platform-as-a-service provider. It offers application hosting, database, object storage, and static site hosting for your projects.

I am using Sevalla for hosting for two reasons:

• Every platform will charge you for creating a cloud resource. Sevalla comes with a $50 credit for us to use, so we won't incur any costs for this example.

• Sevalla has a template for Firecrawl, so it simplifies the manual installation and setup for each resource you will need for Firecrawl.

Login to Sevalla and click on Templates. You can see Firecrawl as one of the templates.

Click “Deploy now” and choose a server in the pop-up, and click “Deploy”. Sevalla will start provisioning the resources we need for running our Firecrawl instance.

Once the deployment is complete, you will see three instances provisioned:

• a Redis Cache

• a server to run Playwright

• The API application

Go to the Firecrawl-API application. Under the deployments section, click on “Visit app” once the deployment is complete.

You can now use your private endpoint in your applications. My API URL is https://firecrawl-api-56t8x.sevalla.app (this is a temporary URL – dont use this), so I can replace api.firecrawl.dev with this URL.

curl -X POST https://firecrawl-api-56t8x.sevalla.app/v2/extract \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://firecrawl.dev/*"],
    "prompt": "Extract the company mission and whether it is open source.",
    "schema": {
      "type": "object",
      "properties": {
        "company_mission": { "type": "string" },
        "is_open_source": { "type": "boolean" }
      }
    }
  }'

If you want to run the project locally by installing applications like Redis, Postgresql, and Playwright, here’s a detailed guide.

Use Cases

Developers and data scientists use Firecrawl for a wide range of tasks. They often rely on it to turn documentation sites into training data for large language models, ensuring that their models can learn from accurate and well-organised sources.

Others use it to collect blog posts or news articles for sentiment analysis, helping them understand trends, opinions, or public reactions across the web.

Firecrawl is also valuable for monitoring web content changes, which is essential for research projects or compliance tracking where up-to-date information is critical.

Teams can also use it to build “chat with your website” AI assistants that can answer questions based on the latest site content.

In each of these cases, Firecrawl ensures that your model receives clean, structured, and consistent data, making it easier to build reliable and intelligent AI systems.

Conclusion

Turning messy websites into readable text used to be one of the toughest parts of building AI systems. Firecrawl changes that. With one API call, you can scrape, crawl, and extract high-quality data that your LLM can immediately understand.

If you’re building anything related to AI, RAG, or data pipelines, Firecrawl is one of those tools you’ll wish you had discovered earlier.

Gaps in APIs can occur before requests reach the APIs, within the code housing the APIs, and even along the path of the APIs’ communication with downstream services, dependencies, or other microservices.

Attackers leverage flaws in APIs to gain access to confidential data, harvest or manipulate data, or even make your service unavailable through distributed denial of service attacks.

In this article, you’ll learn to deploy your APIs in Lambda and apply some security measures pre-function, within the function, and post-function.

Table of Contents

• What is an API?

• Requirements/Prerequisites

• Project Goal

• Project Overall Architecture

  • AWS Set Up

  • Clone Project

  • Set Up Simple Notification Service

  • Set Up Secrets Manager

  • Set Up Internal Lambda

  • Set Up External Lambda

  • Configure Web Application Firewall

  • Configure Cognito User Pools

  • Configure API Gateway

  • Test Setup End-to-End

  • Clean Up

• Improvements

• Conclusion

What is an API?

The focus of this article is the security of Application Programming Interfaces (APIs). An API is an interface that connects two programms or applications, allowing them to exchange data and communicate.

An API can be internal to an organization or it can belong to a third-party that allows other users to consume their data through the API.

Requirements/Prerequisites

While this tutorial is beginner-friendly, you’ll need the following prerequisites to follow along seamlessly:

• A basic knowledge of the AWS Cloud.

• An AWS account with administrator access.

• AWS CLI. You can find the installation guide here. Follow the instructions for your operating system.

• Python. You can visit Python’s official documentation site for a guide on how to download and install Python for your specific operating system.

• Pipenv or any Python virtual environment creation tool. You can find the Pipenv installation guide here.

• A basic knowledge of Git.

• An API client, like Postman or Thunderclient.

Project Goal

By the end of this project, you should be able to deploy APIs in Lambda securely, leveraging AWS cloud-native security services.

Project Overall Architecture

Below is the architecture of the project workflow:

As shown in the architectural diagram, when a user sends a request (a JSON object consisting of the user’s name) to an API hosted in Lambda, the user first gets authenticated by an authentication service called Amazon Cognito.

The request passes through a Web Application Firewall, then an API Gateway. API Gateway will perform a check to see if the user is authorized to access the API using the token that the user sends with the request after authentication. API Gateway then allows the traffic to pass through to the API if the user is authorized.

The user’s request will first get to an External Lambda function, which will then save the user’s name as a message to a Simple Notification Service (SNS) topic. This will then invoke an Internal Lambda to run and log the output in Amazon CloudWatch logs. The SNS topic will be accessed by External Lambda using the SNS’s unique identifier stored in Amazon Secrets Manager.

AWS Set Up

You’ll need to set up an AWS environment to get started. This requires creating an account if you don’t already have one.

Following account creation, a root user is automatically created, with all privileges attached to the user. Security best practice is to create another user with administrator privileges and use this user for subsequent tasks.

Then, create an access key for this user, which usually consists of two parts (Access Key ID and Secret Access Key) by navigating to the following:

IAM —→ Users —→ Create Access key

Follow the prompts and choose the Command Line Interface option. Check the Confirmation box, and go on to create the key. Download the CSV file provided, or manually copy the Access Key ID and Secret Access Key. Save them securely.

Open up your terminal and run the following commands using the AWS CLI:

aws configure

The above command will give some prompts to provide the components of the Access Key created earlier and your default region (the AWS region hosting the service you intend to interact with).

Clone Project

In the next step, you’ll clone the GitHub repository containing the assets and resources used in the project implementation.

Visit the project URL and clone the repository locally.

git clone <repository_clone_url>

Set Up Simple Notification Service

Amazon Simple Notification Service (SNS) connects system components, enabling asynchronous communication and messaging among them.

Find SNS on the console, click on it, and create a topic that your APIs will send messages to. After successfully creating a topic, navigate to the topic, and in the topic details, you’ll find the topic’s ARN. An ARN is an Amazon Resource Name, and it’s a unique string attached to a resource you’ve created on AWS to help identify the resource. Copy the ARN of the topic.

Set Up Secrets Manager

Amazon Secrets Manager is used to store, manage, and retrieve sensitive information such as keys, credentials, tokens, and so on. You’ll store the Topic ARN created earlier. With this approach, you’ll demonstrate how your API can securely access the data and information it needs for its performance.

Go to Secrets Manager on the AWS console and create a secret. Provide the secret’s details, and add a new secret named TOPIC_ARN as the key and the actual SNS Topic ARN as the value.

Next, you’ll create some Lambda functions to serve your APIs and consume the output of the APIs. There’re three Lambda functions to set up. Two of the functions will host APIs, each of which can only be accessed by specific users. These will be referred to as ExternalLambda. The third Lambda will consume the output of the External Lambda functions through SNS.

Set Up Internal Lambda

AWS Lambda is a serverless service on AWS that users can leverage to run application functions or code when needed. You’re billed for your Lambda function based on the number of invocations of the function, the duration each invocation lasted, and the amount of memory allocated to the function. Lambda can be provisioned to use any runtime, such as Python or NodeJS. In this demonstration, you’ll focus on the NodeJS runtime.

Now that you know what Lambda is and does, you can create one. Let’s call the first Lambda function InternalLambda. On the AWS console, search for Lambda, and on the Lambda dashboard, click Create a function and provide the details. We’ll be using Node.js – JavaScript at the backend as the runtime of choice.

For the Permissions details, let Lambda create a default IAM Role. This default role is named according to your function, and the permissions attached to the role allow your Lambda function to send logs to CloudWatch, another AWS service used for monitoring and observability.

As you can see in the last image above, the Lambda function you’ve created needs a trigger and sometimes, a destination. For your InternalLambda, the trigger is the SNS topic we configured earlier. This Lambda will read the messages that’ve been published to it, and then you can access the message from your client or even CloudWatch logs.

To achieve this, click the Add trigger button and provide the details.

Next, you’ll provide the code you want to invoke through Lambda. Find the code in the GitHub repository that you cloned earlier. Paste the code in the Lambda function code space and click on Deploy to deploy the function.

secure-lambda/InternalLambda/index.js

export const handler = async (event) => {
    try {
        console.log('Request successfully received from SNS');                            

        let name = event['Records'][0]['Sns']['Message'];
        let response = {
            statusCode: 200,
            body: JSON.stringify(`Hello ${name}. Greetings from InternalLambda!`),
        };       
        console.log('Response: ', response);                                                
        return response;
    } catch (err) {                            
        let response = {
            statusCode: 500,
            body: JSON.stringify('An error occurred while processing your request.'),
        };

        console.error('Error processing event', err);
        return response;
    }   
};

The function defined in the index.js file above is simply taking the event object sent to it from SNS and extracting the Message attribute within it. We’re using console.log here to view outputs from the function and ensure it behaves as expected. Just don’t use this in a production-ready application.

Set Up External Lambda

You’ll be creating two external Lambda functions: 1 and 2. These two functions will receive user requests, process them, and publish messages to your SNS topic.

On the Lambda console, create another function and name it ExternalLambda1. Allow Lambda to create a default IAM Role, as previously.

Paste the code snippet below in the ExternalLambda1 code space:

secure-lambda/ExternalLambda1/insex.js

import {
  GetSecretValueCommand,
  SecretsManagerClient,
} from "@aws-sdk/client-secrets-manager";

import { SNSClient, 
    PublishCommand 
} from "@aws-sdk/client-sns";

const secretsManagerClient = new SecretsManagerClient();

const snsClient = new SNSClient({});

// Fetch topicArn from AWS Secrets Manager
async function getSecretValue(secretName) {
    try {
        const data = await secretsManagerClient.send(
                            new GetSecretValueCommand({
                            SecretId: secretName,
                            }),
                        );
        if (data.SecretString) {
            return JSON.parse(data.SecretString);
        }   else {
            let buff = Buffer.from(data.SecretBinary, 'base64');
            return JSON.parse(buff.toString("utf-8"));
        }
    } catch (err) {
        console.error('Error retrieving secret', err);                             // added for debugging
        throw err;
    }
}                                        

export const handler = async (event) => {

    let name = event['name'];
    console.log(`Request successfully received from ${name}`);    

    // Retrieve SNS Topic ARN from Secrets Manager
    let topicArn;
    let response;
    try {
        const secret = await getSecretValue('LambdaSNSTopicARN');
        topicArn = secret.TOPIC_ARN;
    } catch (err) {
        response = {
            statusCode: 500,
            body: JSON.stringify('An error occured, try again later.'),
        };
        console.error('Failed to load SNS Topic ARN from Secrets Manager', err);
        return response;        
    }

    // Publish to SNS topic
   try {
        const snsResponse = await snsClient.send(
        new PublishCommand({
            Message: name,
            TopicArn: topicArn,
        })
        );
        console.log("Message published successfully:", snsResponse.MessageId);
        response = {
            statusCode: 200,
            body: JSON.stringify(`Hello ${name}. Greetings from ExternalLambda1! Message forwarded to InternalLambda.`),
        };
        return response;
  } catch (err) {
        response = {
            statusCode: 500,
            body: JSON.stringify(`Sorry ${name}.An error occurred while processing your request.`),
        };
        console.error("Failed to publish message:", err);
        return response;
  }  
};

The code above leverages the AWS SDK to fetch the ARN of the SNS topic created earlier from Secrets Manager. It then publishes a message to the topic.

The SDK already comes installed in the Lambda function. Outside of Lambda, the SDK has to be explicitly installed. The function receives its event from the client via API Gateway, which we’ll configure later.

The SNS topic you created earlier will be the destination for this function. For Lambda to publish a topic to SNS, it needs the necessary permission attached to its IAM Role. AWS can automatically take care of that during your configuration, as shown below.

For the trigger, you’ll use another service known as API Gateway. More on that later.

Follow the same steps to provision another Lambda known as ExternalLambda2.

The outcome of the External Lambda setup is as shown below:

Paste the code below into ExternalLambda2. It performs the same function as ExternalLambda1, but their output differ. Each of the two Lambda functions will be receiving traffic to a specific user that’s authorized to access the function.

secure-lambda/ExternalLambda2/index.js

import {
  GetSecretValueCommand,
  SecretsManagerClient,
} from "@aws-sdk/client-secrets-manager";

import { SNSClient, 
    PublishCommand 
} from "@aws-sdk/client-sns";

const secretsManagerClient = new SecretsManagerClient();

const snsClient = new SNSClient({});

// Fetch topicArn from AWS Secrets Manager
async function getSecretValue(secretName) {
    try {
        const data = await secretsManagerClient.send(
                            new GetSecretValueCommand({
                            SecretId: secretName,
                            }),
                        );
        if (data.SecretString) {
            return JSON.parse(data.SecretString);
        }   else {
            let buff = Buffer.from(data.SecretBinary, 'base64');
            return JSON.parse(buff.toString("utf-8"));
        }
    } catch (err) {
        console.error('Error retrieving secret', err);  
        throw err;
    }
}                                        

export const handler = async (event) => {

    let name = event['name'];
    console.log(`Request successfully received from ${name}`);    

    // Retrieve SNS Topic ARN from Secrets Manager
    let topicArn;
    let response;
    try {
        const secret = await getSecretValue('LambdaSNSTopicARN');
        topicArn = secret.TOPIC_ARN;
    } catch (err) {
        response = {
            statusCode: 500,
            body: JSON.stringify('An error occured, try again later.'),
        };
        console.error('Failed to load SNS Topic ARN from Secrets Manager', err);
        return response;        
    }

    // Publish to SNS topic
   try {
        const snsResponse = await snsClient.send(
        new PublishCommand({
            Message: name,
            TopicArn: topicArn,
        })
        );
        console.log("Message published successfully:", snsResponse.MessageId);
        response = {
            statusCode: 200,
            body: JSON.stringify(`Hello ${name}. Greetings from ExternalLambda2! Message forwarded to InternalLambda.`),
        };
        return response;
  } catch (err) {
        response = {
            statusCode: 500,
            body: JSON.stringify(`Sorry ${name}.An error occurred while processing your request.`),
        };
        console.error("Failed to publish message:", err);
        return response;
  }              
};

Before moving on, you need to modify the External Lambda’s IAM Roles. Currently, IAM Roles only have permissions to write to CloudWatch and SNS (automatically added). External Lambda also needs permission to fetch the ARN of the SNS topic that was created earlier.

The point here is to show how to leverage a secrets manager, such as AWS Secrets Manager, to store sensitive information or data, and still access these securely. This approach is more secure than storing the ARN as an environment variable within Lambda.

Navigate to IAM, and click on Policies tab on the left. This brings you to a list of policies. Next, click on Create policy.

Search for secrets manager in the Policy editor.

Select the permissions Lambda needs to access Secrets Manager. In this case, that would be Read —> GetSecretValue.

Select Specific for Resources, and click on Add ARNs. On the next tab, add the details of the Secrets Manager Secret created earlier.

The Secret’s ARN will be populated here.

Next, give the policy a name and create it.

Next, navigate to Roles, and search for the IAM Roles assigned to the External Lambda functions. These are named according to the Lambda.

Click Add permissions to add a new permission to the IAM Role selected.

Configure Web Application Firewall

A firewall is a system placed in front of an application, workload, APIs, and so on to inspect traffic, filter it, and either allow or block the traffic based on some preconfigured rules.

For this project, you’ll use the AWS Web Application Firewall (WAF) service to inspect user requests before routing the traffic to your APIs running in Lambda.

Head over to the AWS console and search for WAF.

Click on the IP sets tab on the left. This will enable you to create a list of IP addresses that you want to allow (as in this case) or deny.

The IP addresses should include a CIDR block. For instance, if adding a single IP address, it should be X.X.X.X/32. The same applies to IP address ranges such as X.X.X.X/24.

Next, click on the Web ACLs tab, then Create web ACL.

Choose Regional resources as the Resource type, and enter your region. It’s best to keep all resources you’re creating in this project within the same region. Give your Web ACL a name, then click next.

Add rules to the Web ACL.

Choose a rule type. In this case, you’ll use IP set, and give the rule a name. Choose the IP set created earlier.

Select Source IP address, and Count as the Action. For this project, you’ll focus on counting the requests sent to your APIs. But as shown in the image below, you can perform other actions, such as allow, block, and so on.

Your final rule configuration will appear this way.

Scroll down, then click on Create web ACL.

Configure Cognito User Pools

Amazon Cognito is an identity management service used for creating and managing users. You can leverage it to authenticate and authorize users to applications, APIs, or other workloads.

You’ll create User Pools within Cognito and add a user to each pool. You’ll configure how these users can be authenticated and authorized to access the External Lambda functions already created.

Search for Cognito on AWS.

Click on Get started for free, then Create user pool.

Select Single-page application (SPA), give the User pool the name MyUserPool1, and select Email as an option for sign-in. This means the main attribute users will provide at signup and sign-in will be their email address. Leave everything else as the default. We’ll keep things as simple as possible.

After creating the User pool, you’ll find the page shown below. You can view the login and signup page for the pool you’ve just created by clicking on the View login page button.

You can add App clients to your User Pool. By default, a client named MyUserPool1 will be added to the pool. Navigate to your User pool, and click on App clients to see details of this client. Note the Client ID. You’ll also make some edits to the App client by clicking on the Edit button.

You’ll edit the Authentication flows field by ticking the Sign in with username and password… and Sign in with server-side administrative credentials… boxes. These changes will enable you to authenticate the user who will be added to this client programmatically, rather than through a UI. With this approach, we can fetch the token assigned to the user by Cognito and use this token to authorize access to Lambda.

Now, add a user to this pool. The user needs a valid email address. You’ll need the login page URL to create the user.

You need access to the email used to create the user. Fetch the code sent to the email address and submit to confirm the account.

Follow the same steps and create another User pool named MyUserPool2. Add a user with a different email to this pool.

Configure API Gateway

API Gateway is a service used to manage access and route traffic to API backend services such as APIs. It serves as a reverse proxy and provides an extra layer of security for backend services.

You’ll configure API Gateway to direct traffic to your Lambda functions.

Navigate to API Gateway and click on Create an API.

Select the REST API option —→ Build.

Select New API, provide a name, and choose Regional as the API endpoint type. IP address type can be IPv4 or Dualstack. We’ll select IPv4 here. Then create.

An important part of API Gateway configuration for this project is the Authorizer. API Gateway uses Authorizer to allow traffic from clients to backend services.

You’ll create two Authorizers. Each will be connected to one of the User pools you configured earlier. On the left-hand side of the API Gateway you configured, click on Authorizers —→ Create authorizer.

Provide the name AGAuthorizer1, and select Cognito as the Authorizer type. Add the User pool for MyUserPool1 created earlier. For the Token source, use Authorization. When you send a request from your API client, a token will be added to the request header for authorization. The token’s key will be named Authorization, while the value will be the token itself.

Create another Authorization for MyUserPool2 the same way.

Both Authorizers will appear this way.

Next, you’ll create resources and endpoints within the API Gateway that you’ve defined.

A resource in API Gateway is used to group certain endpoints within a specific path. You’ll define two resources within the API Gateway you’ve created. This will create two different paths, <BASE_URL>/<RESOURCE1> and <BASE_URL/RESOURCE2>.

On the API Gateway dashboard, navigate to your Gateway, click on Create resource, define your root path (‘/’ in your case), and provide the resource name (lambda1).

Create another resource named lambda2.

Now, click on /lambda1, then Create method to define an endpoint within this resource. You’ll use the POST method to send requests to the backend service via this endpoint.

For the backend service or Integration type, select Lambda function, and provide the ARN of ExternalLambda1.

For Authorization, select AWS IAM —→ Cognito user pool authorizers —→ AGAuthorizer1. Leave other configurations, then create the endpoint.

Repeat the same step to create a POST method for /lambda2 resource. The method should be attached to ExternalLambda2, and AGAuthorizer2.

The API Gateway you’ve created needs to be deployed to become accessible. Deployment is usually done to a Stage.

Click on Deploy API, select New stage and name the stage development. Then, deploy.

After deployment to a stage, an invoke URL will be provided. This will serve as the base URL for the endpoints you’ve defined.

The stage you’ve created needs some modifications for enhanced security. Firstly, you need to attach the WAF that you created earlier. Secondly, the default rate limit for the API deployed to this stage is 10000. Rate limit restricts excessive resource consumption and protects your API from abuse. For this project, you can reduce the limit to 50.

To test the API Gateway set up, click on the endpoint you want to test, then the Test button. This initial test doesn’t need any authorization, since the test is done directly within the Gateway.

Add JSON data as the Request body. The key will be name, and the value will be any string.

The response sent back from ExternalLambda1 shows a status code of 200, and a response body containing exactly the message expected from the Lambda function.

If you head over to CloudWatch Log groups, you should also find the Log groups that were automatically created for the Lambda functions. Click on the Log group for ExternalLambda1 and navigate to the latest Log stream. You should find the logs for the request you’ve just made from API Gateway.

Test Setup End-to-End

To test our setup properly, and from the internet, send the same request from your API client with no additional information in the request header. This should return a 401 error – Unauthorized. This is expected.

API Gateway expects an authorization token from each request it receives before routing traffic to the appropriate backend service. It validates this token through Cognito.

You’ll mimic a user login for each user added to Coginito User pools to get a token for the user. This token will then be sent alongside any request. To achieve this, you’ll use the two Python scripts I’ve provided below:

secure-lambda/auth-scripts/user1.py

import boto3

client = boto3.client("cognito-idp")

response = client.initiate_auth(
    AuthFlow="USER_PASSWORD_AUTH",  # or ADMIN_USER_PASSWORD_AUTH if using admin creds
    AuthParameters={
        "USERNAME": "",             # user1 email
        "PASSWORD": ""              # user1 password
    },
    ClientId=""                     # Cognito App Client ID
)

id_token = response["AuthenticationResult"]["IdToken"]
access_token = response["AuthenticationResult"]["AccessToken"]
refresh_token = response["AuthenticationResult"]["RefreshToken"]

print("ID Token:", id_token)

Using the Python boto3 library, you’ll initiate an authentication request to Cognito. Provide the email address and password of the user in MyUserPool1. Also, add the Client ID of the App client.

To run the script, create an isolated environment using Pipenv, uv, or a similar library. Install the dependency used in the project as defined in the Pipfile, and run the script with the Pipenv shell.

pipenv install
pipenv shell
Python secure-lambda/auth-scripts/user1.py

The Python command will return with a token assigned to the user. Next, you use this token to authorize a user to access ExternalLambda1.

Ensure that the URL for the POST request is in the format: <BASE_URL/lambda1>. You should receive a response from API Gateway indicating success.

Now try accessing ExternalLambda2 using User1 token. You should get an Unauthorized message. Note that user1 will always receive an unauthorized message when it tries accessing ExternalLambda1 without an Authorization token in the header, a wrong token, or when it tries accessing ExternalLambda2, which it is not authorized to access.

Repeat the process with User2 using the token generated for the user in MyUserPool2. First, test access to ExternalLambda2 without a token in the request header.

Then test access with the token.

Next, try accessing ExternalLambda1 using User2.

You can also view the outcome of some of the requests made by your client on CloudWatch Logs.

Also, since WAF has been configured previously to count requests (although, in a real scenario, you want to achieve much more with WAF, such as allow or block certain traffic), you can view activities captured by WAF by navigating to the service on AWS, then searching for the WAF you configured, and navigating to Traffic overview.

You can find other details, such as the client device types and where requests originated.

Clean Up

It’s important to clean up the resources created so far after the hands-on exercise. Due to the dependencies among the resources, trying to delete a resource that another resource depends on may lead to an error. So, you should delete them in this order:

• Secrets Manager

• Cognito – Users, App Client, then User Pool

• API Gateway – Endpoints/ Methods, Resources, API, Stage

• Web Application Firewall – IP Set, Web ACL

• All Lambda Functions

• Lambda IAM Roles and the policies attached to them

• CloudWatch Log Group for all the Lambda functions

• SNS Topic

Also, you can deactivate or delete the credentials created for your IAM Admin user if not in use.

Improvements

Consider the following areas to improve, apply best practices to, and enhance the security posture of your systems further.

1. Use of API keys

2. Third-party API consumption

3. API inventory management/ documentation

4. Resource provisioning using Infrastructure as Code

Conclusion

Security at every layer of an IT system is not negotiable. In this project, we’ve demonstrated how to leverage cloud-native solutions to secure APIs hosted in a serverless service, allowing only authorized users access to the APIs.

I’m Agnes Olorundare, and you can find out more about me on LinkedIn.

Performing repetitive tasks while testing APIs is stressful and time-wasting. For example, the process of retrieving, copying and pasting new authentication tokens for use in Postman is repetitive. You can simplify this process by using Postman scripts to store auth tokens and then reuse them without repeating the copy and paste steps.

To practice along with this guide, you should have:

• The Postman API client installed on your computer

• Experience in making API requests with Postman

• A backend application that uses JWT authentication and has its documentation in your Postman client

If you don’t have a backend application setup, I created one that you can clone from GitHub at orimdominic/freeCodeCamp-postman-api-jwt.

By the end of this article, you should be able to simplify the process of obtaining and reusing authentication tokens across your API requests. You should also have a practical understanding of some scripts necessary for use in other areas of software testing with Postman.

Table of Contents

• Table of Contents

• What are Postman Scripts?

• How to Simplify Your JWT Authentication Process

  • Authenticate to Get the Token

  • How to Save the Token in a Variable with a Postman Script

  • How to Use the Variable in a Request

• Next Steps

What are Postman Scripts?

Postman scripts are blocks of JavaScript code that you can write and run within the Postman API client to automate and enhance API testing workflows. You can use Postman scripts to add code to run before and after API requests. These scripts can be used to:

• Add logic and process data from API requests

• Write test assertions for API responses

• Run automated tests on API endpoints

You can find Postman scripts under the Scripts tab of an API request. Code written in the Pre-request tab runs before the request is made and code written in the Post-response tab runs after the response is made.

How to Simplify Your JWT Authentication Process

In summary, you will carry out the following steps to achieve the objective of this tutorial:

1. Authenticate to get the token

2. Save the token in a collection variable with Postman scripts

3. Use the variable in an API request

Authenticate to Get the Token

To get started, carry out the following steps:

1. Start your backend application and make sure it is running successfully.

2. Open up your Postman application and go to the API request for signing in to get a JWT.

3. Make an API request to the sign in endpoint and take note of the JSON response schema.

The highlighted part of the image above shows the JSON response from a successful sign in request. In the response schema, the auth token to be used for authorization is in the data.token field. You will use Postman scripts to store this token in a variable and then use the variable in the Authorization header of requests that require authorization.

How to Save the Token in a Variable with a Postman Script

In Postman, click on the Scripts tab next to the Body tab. If the Postman application window is small, you may need to click a dropdown to see it. Next, click on the Post-response tab. In the text area to the right, you will write the script to capture the auth token from the response and store it in a Postman variable. Copy the JavaScript code below and paste it into the text area.

if (pm.response.code == 200) {
    const token = pm.response.json().data.token
    pm.collectionVariables.set("auth_token", token)
}

Postman scripts use the pm identifier to access and modify information in the Postman environment. The script above uses pm to first ensure that the request was successful by checking if the response status code is 200.

Inside the conditional statement, pm.response.json().data.token is used to get the authentication token from the JSON response and store it in a collection variable called auth_token. If auth_token doesn’t exist already, it is created and its value is set to the value of token. If it exists already, its value is replaced.

To confirm that auth_token has been set, click on the name of the collection (labelled 1 in the screenshot above) and then click on the Variables tab (labelled 2 in the screenshot above). Next, instead of repeatedly copying the token and pasting it in the Authorization header of your requests, you will use auth_token in the Authorization header of your requests.

How to Use the Variable in a Request

Reference the collection variable in the Authorization header by surrounding it with double curly braces {{auth_token}}. When you make an API request, Postman will use the value referenced by {{auth_token}} as the Authorization header.

If another authentication request causes the value of auth_token to be updated, you no longer need to copy the new auth token. The script in the post-response tab will update the auth_token value and you can go on with making API requests smoothly. No need for repeatedly copying and pasting - Don’t Repeat Yourself (DRY).

Next Steps

In this tutorial, you have learnt how to use Postman scripts to set environment variables in Postman. You have also learnt how to eliminate the process of repeatedly copying and pasting auth tokens for use in API requests.

For guides on writing assertion tests for your APIs, check out the Test API Functionality and Performance in Postman guide by Postman.

In an earlier article, I walked through building a Next.js API and deploying it with Sevalla. The example stored data in a PostgreSQL database and handled requests directly. That worked fine, but as traffic grows, APIs that hit the database on every request can slow down.

This is where caching comes in. By adding Redis as a cache layer, we can make our Next.js API much faster and more efficient. In this article, we’ll see how to add Redis caching to our API, deploy it with Sevalla, and show measurable improvements.

In the last article, I explained the API in detail. So you can use this repository to start with as the base for this project.

Table of Contents

• Why Caching Matters

• What is Redis?

• Setting Up the Project

• Provisioning Redis

• Updating Cache on Reads

• Updating Cache on Writes

• Deploying to Sevalla

• Why Redis Works Well with Next.js APIs

• Conclusion

Why Caching Matters

Every time your API hits the database, it consumes time and resources. Databases are great at storing and querying structured data, but they aren’t optimized for speed at scale when you need to serve thousands of read requests per second.

Caching solves this by keeping frequently accessed data in memory. Instead of asking the database every time, the API can return data directly from cache if it’s available. Redis is perfect for this because it’s an in-memory key-value store designed for performance.

For example, if you fetch the list of users from the database on every request, it might take 200ms to run the query and return results. With Redis caching, the first request stores the result in memory, and subsequent requests can return the same data in less than 10ms. That’s an order-of-magnitude improvement.

What is Redis?

Redis is an in-memory data store that works like a super-fast database. Instead of writing and reading from disk, it keeps data in memory, which makes it incredibly fast. That’s why it’s often used as a cache, where speed is more important than long-term storage.

It’s designed to handle high-throughput workloads with very low latency, which means it can respond in microseconds. This makes it a perfect fit for use cases like caching API responses, storing session data, or even powering real-time applications like chat systems and leaderboards.

Unlike a traditional database, Redis focuses on simplicity and speed. It stores data as key-value pairs, so you can quickly fetch or update values without writing complex queries. And because it supports advanced data types like lists, sets, and hashes, it’s much more flexible than a plain key-value store.

When combined with an API like the one we built in Next.js, Redis helps you reduce load on the main database and deliver blazing-fast responses to clients.

Setting Up the Project

Let’s clone the repository:

git clone git@github.com:manishmshiva/nextjs-api-pgsql.git next-api

Now let’s go into the directory and do an npm install to install the packages.

cd next-api
npm i

Create a .env file and add the database URL from Sevalla into an environment variable.

cat .env

The .env file should look like this:

PGSQL_URL=postgres://<username>:<password>-@asia-east1-001.proxy.kinsta.app:30503/<db_name>

Now let’s make sure the application works as expected by starting the application and making a couple of API requests.

Starting the app:

npm run dev

Let’s make sure the database is connected. Go to localhost:3000 on your browser. It should return the following JSON:

Let’s create a new user. To create a new entry in the DB using Postman, send a POST request with the following JSON:

{"id":"d9553bb7-2c72-4d92-876b-9c3b40a8c62c","name":"Larry","email":"larry@example.com","age":"25"}

Let’s ensure the record is created by going to localhost:3000/users in the browser.

Great. Now let’s cache these APIs using Redis.

Provisioning Redis

Let’s go to Sevalla’s dashboard and click on “Databases”. Choose “Redis” from the list, and leave the rest of the options as defaults.

Once the database is created, switch on the “external connection” option and copy the publicly accessible URL.

This is how it should look in the .env file:

REDIS_URL=redis://default:<password>@<host>:<port>

Now install a Redis client for Node.js:

npm install ioredis

We can now connect to Redis and use it as a cache layer for our users API. Let’s see how to implement caching.

Updating Cache on Reads

Here’s the updated users/route.ts that uses Redis:

import { NextResponse } from "next/server";
import { Client } from "pg";
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

async function readUsers() {
  const client = new Client({
    connectionString: process.env.PGSQL_URL,
  });
  await client.connect();

  try {
    const result = await client.query("SELECT id, name, email, age FROM users");
    return result.rows;
  } finally {
    await client.end();
  }
}

export async function GET() {
  try {
    // Check cache first
    const cached = await redis.get("users");
    if (cached) {
      return NextResponse.json(JSON.parse(cached));
    }

    // Fallback to database if not cached
    const users = await readUsers();

    // Store result in cache with 60s TTL
    await redis.set("users", JSON.stringify(users), "EX", 60);

    return NextResponse.json(users);
  } catch (err) {
    return NextResponse.json({ error: "Failed to fetch users" }, { status: 500 });
  }
}

Now, when you hit /users:

1. The API first checks Redis.

2. If the data exists, it returns it instantly.

3. If not, it queries PostgreSQL, saves the result in Redis, and then returns it.

This makes repeated requests extremely fast. You can adjust the cache expiry (EX 60) depending on how fresh your data needs to be.

Without Redis caching, fetching /users ten times means ten database queries. Each might take around 150–200ms depending on database size and network latency.

With Redis, the first request still takes ~200ms since it populates the cache. But every request after that is nearly instant, often under 10ms. That’s a 20x improvement.

This speedup matters when your API faces hundreds or thousands of requests per second. Caching not only reduces latency but also lightens the load on your database.

Updating Cache on Writes

Right now, only GET requests use the cache. But what if we add new users? The cache would still return the old data.

The solution is to update or clear the cache whenever a write happens. Let’s update the POST handler:

export async function POST(req: Request) {
  try {
    const body = await req.json();
    const client = new Client({
      connectionString: process.env.PGSQL_URL,
    });
    await client.connect();

    const query = `
      INSERT INTO users (id, name, email, age)
      VALUES ($1, $2, $3, $4)
      RETURNING *;
    `;

    const result = await client.query(query, [
      body.id,
      body.name,
      body.email,
      body.age,
    ]);

    await client.end();

    // Invalidate cache so next GET fetches fresh data
    await redis.del("users");

    return NextResponse.json(result.rows[0]);
  } catch (err) {
    return NextResponse.json({ error: "Failed to add user" }, { status: 500 });
  }
}

Now whenever a new user is created, the cache for users is cleared. The next GET request will fetch from the database, refresh the cache, and then continue serving cached data.

Deploying to Sevalla

Push your code to GitHub or fork my repository. Now lets go to Sevalla and create a new app.

Choose your repository from the dropdown and check “Automatic deployment on commit”. This will ensure that the deployment is automatic every time you push code. Choose “Hobby” under the resources section.

Click “Create” and not “Create and deploy”. We haven’t added our PostgreSQL URL and Redis URL as environment variables, so the app will crash if you try to deploy it.

Go to the “Environment variables” section and add the key “PGSQL_URL” and the URL in the value field. Do the same for the “REDIS_URL” key and add the Redis URL.

Now go back to the “Overview” section and click “Deploy now”.

Once deployment is complete, click “Visit app” to get the live URL of your API. You can replace localhost:3000 with the new URL in Postman and test your API.

Why Redis Works Well with Next.js APIs

Redis is lightweight, blazing fast, and perfect for caching API responses. In the context of Next.js, it fits naturally because:

• The API routes run server-side where Redis can be queried directly.

• Caching logic is simple to add around database calls.

• Redis can be used for more than caching – things like rate limiting, session storage, and pub/sub are also common patterns.

By combining Next.js, PostgreSQL, and Redis on Sevalla, you get a stack that is fast, scalable, and easy to deploy.

Conclusion

Caching isn’t just an optimization – it’s a necessity for real-world APIs. Next.js helps you build robust backend APIs that can be deployed easily. By adding Redis to the mix, those APIs can handle scale without breaking a sweat.

Sevalla ties it all together by providing managed PostgreSQL, Redis, and app hosting in one place. With a few environment variables and a GitHub repo, you can go from local dev to a production-ready, cached API in minutes.

Hope you enjoyed this article. Signup for my free AI newsletter TuringTalks.ai for more hands-on tutorials on AI. You can also find me on Linkedin.

I’ve recently written an article on working with Next.js API and deploying it to production. In this case, I would’ve used a JSON file as a mini-database.

But JSON or any type of file storage isn’t fit for a production application. This is because file-based storage isn’t designed for concurrent access, so multiple users writing data at the same time can cause corruption or loss.

It also lacks indexing and query capabilities, making it slow as data grows. Backups, security, and scalability are also harder to manage compared to a proper database.

In short, while JSON files work for demos or prototypes, production systems need a database that can handle concurrency, large datasets, complex queries, and reliable persistence.

So in this article, we'll walk through how to build a REST API with Next.js, store data in a Sevalla-managed database, and deploy the whole project to production using Sevalla's PaaS infrastructure.

Table of Contents

• What is Next.js?

• Installation and Setup

• How to Build a NextJS API

• Provisioning a Database in Sevalla

• Deploying to Sevalla

• Conclusion

What is Next.js?

Next.js is an open-source React framework developed by Vercel. It's known for server-side rendering, static generation, and seamless routing. But beyond its frontend superpowers, it allows developers to build backend logic and APIs through its file-based routing system. This makes Next.js a great choice for building full-stack apps.

Installation and Setup

To get started, make sure Node.js and NPM are installed.

$ node --version
v22.16.0

$ npm --version
10.9.2

Now, create a new Next.js project:

npx create-next-app@latest

The result of the above command will ask you a series of questions to setup your app:

What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack for `next dev`?  No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*

But for this tutorial, we aren’t interested in a full stack app – just an API. So let’s re-create the app using the — - api flag.

$ npx create-next-app@latest --api

It will still ask you a few questions. Use the default settings and finish creating the app.

Once the setup is done, you can see the folder with your app name. Let’s go into the folder and run the app.

$ npm run dev

Your API template should be running at port 3000. Go to http://localhost:3000 and you should see the following message:

{
"message": "Hello world!"
}

How to Build a NextJS API

Now that we’ve set up our API template, let's write a basic REST API with two endpoints: one to create data and one to view data

The API code will reside under /app within the project directory. Next.js uses file-based routing for building URL paths.

For example, if you want a URL path /users, you should have a directory called “users” with a route.ts file to handle all the CRUD operations for /users. For /users/:id, you should have a directory called [id] under “users” directory with a route.ts file. The square brackets are to tell Next.js that you expect dynamic values for the /users/:id route.

Here is a screenshot of the setup. Delete the [slug] directory that comes with the project since it won’t be relevant for us.

• The route.ts file at the bottom handles CRUD operations for / (this is where the response “hello world” was generated from)

• The route.ts file under /users handles CRUD operations for /users

While this setup can seem complicated for a simple project, it provides a clear structure for large-scale web applications. If you want to go deeper into building complex APIs with Next.js, here is a tutorial you can follow.

The code under /app/route.ts is the default file for our API. You can see it serving the GET request and responding with “Hello World!”:

import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello world!" });
}

Now we need two routes:

• GET /users which lists all users

• POST /users which creates a new user

For this project, we’ll use a database to store our records. We’re not going to install a database on our local machine. Instead, we’ll provision the database in the cloud and use it with our API. This approach is common in test / prod environments to ensure data consistency.

Provisioning a Database in Sevalla

Sevalla is a modern, usage-based Platform-as-a-service provider and an alternative to sites like Heroku or to your self-managed setup on AWS. It combines powerful features with a smooth developer experience.

Sevalls offers application hosting, database, object storage, and static site hosting for your projects. It comes with a generous free tier, so we’ll use it to connect to a database as well as deploy our app to the cloud.

If you are new to Sevalla, you can sign up using your GitHub account to enable direct deploys from your GitHub. Every time you push code to your project, Sevalla will auto-pull and deploy your app to the cloud.

Once you login to Sevalla, click on “Databases”.

Now let’s create a PostgreSQL database.

Use the default settings. Once the database is created, it will disable the external connections by default for security to ensure no one outside our server can connect to it. Since we want to test our connection from our local machine, let’s enable an external connection.

The value we need to connect to the database from our local endpoint is “url” under external connection. Create a file called .env in the project and paste the URL in the below format:

PGSQL_URL=postgres://<username>:<password>-@asia-east1-001.proxy.kinsta.app:30503/<db_name>

The reason we use .env is to store environment variables specific to the environment. In production, we won’t need this file (never push .env files to GitHub). Sevalla will give us the option to add environment variables via the GUI when we deploy the app.

Now let’s test our database connection. Install the pg package for Node to interact with PostgreSQL. Let’s also install the TypeScript extension for pg to support TypeScript definitions.

$ npm i pg
$ npm install --save-dev @types/pg

Change the route.ts that served “hello world” to the below:

// app/api/your-endpoint/route.ts
import { NextResponse } from "next/server";
import { Client } from "pg";

export async function GET() {
  const client = new Client({
    connectionString: process.env.PGSQL_URL,
  });

  try {
    await client.connect();
    await client.end();
    return NextResponse.json({ message: "Connected to database" });
  } catch (error) {
    console.error("Database connection error:", error);
    return NextResponse.json({ message: "Connection failed" }, { status: 500 });
  }
}

Now when your app and go to localhost:3000, it should say “connected to database”.

Great. Now let’s write our two routes, one to create data and the other to view the data we created. Use this code under users/route.ts:

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { Client } from "pg";

// Define the structure of a User object
interface User {
  id: string;
  name: string;
  email: string;
  age: number;
}

// Create a PostgreSQL client
function getClient() {
  return new Client({
    connectionString: process.env.PGSQL_URL,
  });
}

// Fetch all users from the database
async function readUsers(): Promise<User[]> {
  const client = getClient();
  await client.connect();

  try {
    const result = await client.query("SELECT id, name, email, age FROM users");
    return result.rows;
  } finally {
    await client.end();
  }
}

// Insert or update users in the database
async function writeUsers(users: User[]) {
  const client = getClient();
  await client.connect();

  try {
    const insertQuery = `
      INSERT INTO users (id, name, email, age)
      VALUES ($1, $2, $3, $4)
      ON CONFLICT (id) DO UPDATE SET
        name = EXCLUDED.name,
        email = EXCLUDED.email,
        age = EXCLUDED.age;
    `;

    for (const user of users) {
      await client.query(insertQuery, [user.id, user.name, user.email, user.age]);
    }
  } finally {
    await client.end();
  }
}

// Handle GET request: return list of users
export async function GET() {
  try {
    const users = await readUsers();
    return NextResponse.json(users);
  } catch (err) {
    console.error("Error reading users from DB:", err);
    return NextResponse.json({ error: "Failed to fetch users" }, { status: 500 });
  }
}

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const users: User[] = Array.isArray(body) ? body : [body];

    await writeUsers(users);

    return NextResponse.json({ success: true, count: users.length });
  } catch (err) {
    console.error("Error writing users to DB:", err);
    return NextResponse.json({ error: "Failed to write users" }, { status: 500 });
  }
}

Now when you go to localhost:3000/users, it will give you an error because the users table does exist. So let’s create one.

In the database UI, click on “Studio”. You’ll get a visual editor for your database where you can manage your data directly (pretty cool, right?).

Press the “+” icon and choose “create table”. Create the table with the schema below. Click the “add column” link to create new columns.

Click “create table and you should see the table created as below:

Let’s add a dummy record using “add record” button to use it to test our API. The id field should be in UUID format (and you can generate one here).

Now let’s test our API.

You should see the user you created as the response to the localhost:3000/users query. Now let’s create a new user using our API.

We’ll use Postman for this since its easy to create POST requests using Postman. We’ll send a sample data under “body” → “raw” → “JSON”.

The response from Postman should be as below:

Now going to localhost:3000/users, you should see the new record created.

Great job! Now let’s get this app live.

Deploying to Sevalla

Push your code to GitHub or fork my repository. Now lets go to Sevalla and create a new app.

Choose your repository from the dropdown and check “Automatic deployment on commit”. This will ensure that the deployment is automatic every time you push code. Choose “Hobby” under the resources section.

Click “Create” and not “Create and deploy”. We haven’t added our PostgreSQL URL as an environment variable, so the app will crash if you try to deploy it.

Go to the “Environment variables” section and add the key “PGSQL_URL” and the URL in the value field.

Now go back to the “Overview” section and click “Deploy now”.

Once deployment is complete, click “Visit app” to get the live URL of your API. You can replace localhost:3000 with the new URL in Postman and test your API.

Congratulations – your app is now live. You can do more with your app using the admin interface, like:

• Monitor the performance of your app

• Watch real-time logs

• Add custom domains

• Update network settings (open/close ports for security, and so on)

• Add more storage

Conclusion

Next.js is no longer just a frontend framework. It’s a powerful full-stack platform that lets you build and deploy production-ready APIs with minimal friction. By pairing it with Sevalla’s developer-friendly infrastructure, you can go from local development to a live, cloud-hosted API in minutes.

In this tutorial, you learned how to set up a Next.js API project, connect it to a cloud-hosted PostgreSQL database on Sevalla, and deploy everything seamlessly. Whether you're building a small side project or a full-scale application, this stack gives you the speed, structure, and scalability to move fast without losing flexibility.

Hope you enjoyed this article. I’ll see you soon with another one. You can connect with me here or visit my blog.

This beginner-friendly tutorial is designed for junior developers and anyone new to React. You'll learn how to fetch data from an API, then store and display it in your React app. No advanced knowledge required – we'll break everything down step by step, so you can follow along and build confidence as you go.

We'll be using React, Vite, Axios, and Tailwind CSS to build a simple app that retrieves and displays data from a public API. First, we’ll fetch data using the built-in fetch method. Then we’ll refactor it using Axios, a popular library that simplifies HTTP requests.

Prerequisites

To follow along with this article, you should:

• Be familiar with basic React concepts like components and useState

• Know what an API is and that it returns data (usually in JSON)

• Have some experience with JavaScript promises and the .then() method. (If you’ve seen or used .then() before, that’s enough – we'll build on that).

• Be comfortable using map() to render lists from arrays (the data we get from the API)

• Be able to run a React project using tools like Vite or Create React App

Table of Contents

1. What is an API and Why Do We Need it?

2. Types of APIs You’ll Encounter

3. Tools We’ll Use

4. How to Fetch Data with React

   • How to Fetch Data with fetch()

   • Refactor with Axios

5. How to Handle Loading and Error States

   • What is a Loading State?

   • What is an Error State?

6. How to Keep Your API Keys Safe

   • Why it's Important:

7. Fun Public APIs to Practice With

8. Conclusion

What is an API and Why Do We Need it?

An API, or Application Programming Interface, is a way for different systems to communicate. Think of it like a waiter at a restaurant. You tell the waiter what you want from the menu (the request), they take that order to the kitchen (the server), and then bring your food back to the table (the response).

In web development, APIs let your frontend application talk to a backend service. Most of the time, this communication happens through HTTP requests. You make a request to a specific URL (called an endpoint), and you get a response, usually in JSON (JavaScript Object Notation) format. JSON is lightweight, easy to read, and works well with JavaScript.

Here’s a basic GET request example:

GET https://jsonplaceholder.typicode.com/users

This GET request asks the server for a list of users. The response will look something like this:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "JohnDOe@email.com",
  },
  {
    "id": 2,
    "name": "Jane Doe",
    "email": "JaneDoe@email.com",
  },
   //...more users
]

Your React app can grab this JSON, store it in state, and display it in the browser. That’s the basic API cycle you’ll see again and again in real-world applications:

• Make the request

• Wait for the response

• Parse the JSON

• Use the data in your UI

Understanding APIs and JSON is essential. You’ll use them to fetch user profiles, submit forms, update dashboards, search databases, and so much more.

Types of APIs You’ll Encounter

Not all APIs are the same. Understanding the types of APIs you'll come across will help you know what tools or steps you’ll need to work with them.

1. Public APIs (No Key Required)

These are open-access APIs that anyone can use. They don’t require authentication or an API key. They're great for testing, learning, and building demo apps.

Example:

GET https://jsonplaceholder.typicode.com/users

2. Public APIs (With API Key)

Some APIs are public, but still require an API key. This helps the provider track usage and prevent abuse. You'll usually sign up to get a free key.

Example:

GET https://newsapi.org/v2/top-headlines?country=us&apiKey=YOUR_API_KEY

• https://newsapi.org/v2/top-headlines – the actual API endpoint

• country=us – a query parameter specifying you want “US headlines”

• apiKey=YOUR_API_KEY – this is your personal API key you get after signing up on newsapi.org

To use these APIs, you’ll need to:

• Sign up on the provider’s site

• Store your key (safely) in your app (we will explore that later on)

• Pass it as a query parameter or header

3. Private APIs

These are usually used internally in companies. They often require more advanced forms of authentication, like OAuth tokens or session cookies. You won’t typically use these unless you’re working on the backend or within a team project.

4. Using Bearer Tokens for API Authentication

When working with modern APIs, it's common to encounter APIs that require authentication using a Bearer token instead of a simple API key in the URL. The only difference here is that you pass in an object that contains the Bearer token instead of just the api key variable (for example, The Movie Database (TMDB) API).

This approach is more secure because it keeps the token out of the URL and browser history. It also aligns with token-based authentication standards like OAuth 2.0.

Note: When working with third-party APIs, always check the documentation to see how authentication should be handled. Authentication methods vary – some APIs require passing the key in the URL, others expect it in the headers.

Tools We’ll Use

• React: our JavaScript UI library of choice

• Tailwind CSS: For quick styling

• fetch: Native browser method for making HTTP requests

• Axios: Optional library that makes requests more convenient

Learning how to use these tools and methods will make it easier to adapt to different production methods and environments.

How to Fetch Data with React

Now you need to understand the basic structure and tools you need in order to fetch data with React and store that data to use in your components. To do this properly, you'll need to understand a few core tools and concepts:

• useState hook: Lets you create and manage local state inside your component. You'll use it to hold the data you fetch, and track things like whether you're still loading or if there was an error.

• useEffect hook: Allows you to perform operations that need to run after the component renders, such as fetching data, subscribing to events, or updating the DOM.

• HTTP Requests: These are how you talk to APIs. You can use the browser-native fetch() method or third-party tools like Axios.

A basic data fetching flow looks like this:

• Set up state to hold your data when it arrives

• Use the useEffect() hook to make the API call

• Handle loading and error states

• Store and display the data once it arrives

Now that you’ve got the fundamentals, let’s walk through two ways to fetch data: first using fetch(), then using Axios.

How to Fetch Data with fetch()

The fetch() method is a native browser feature that allows you to send HTTP requests directly from the frontend. It’s useful for making basic API calls without any additional libraries.

To use fetch() in React, you'll typically follow this pattern:

• Use the useEffect() hook to ensure the fetch call only runs once when the component mounts.

• Call fetch('url') to send the HTTP GET request.

• Use .json() to parse the JSON response.

• Store the response in state using useState().

Let’s see an example:

Import the necessary hooks and make the fetch call inside useEffect.js:

import { useEffect, useState } from 'react';

function App() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch('https://jsonplaceholder.typicode.com/users')
      .then(res => res.json())
      .then(data => setUsers(data));
   // res.json() converts the raw response into JSON.
   // setUsers(data) updates the React state with that JSON and stores it in state so you can access it.

  }, []);

  return (
    <div className="p-6 max-w-4xl mx-auto">
      <h1 className="text-2xl font-bold mb-4">User List (using fetch)</h1>
      <ul className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
        {users.map(user => (
          <li key={user.id} className="bg-white shadow p-4 rounded-xl">
            <h2 className="text-lg font-semibold">{user.name}</h2>
            <p className="text-sm text-gray-600">{user.email}</p>
            <p className="text-sm text-gray-600">{user.company.name}</p>
          </li>
        ))}
      </ul>
    </div>
//Map through the stored data in the state and display the contents
// in a list and access the properties from the data(user.name)
  );
}

export default App;

Refactor with Axios

Axios is a third-party library that makes HTTP requests easier and more reliable. While fetch() is built into the browser, Axios simplifies several things, like automatic JSON parsing and cleaner error handling.

Why Use Axios Over fetch:

• Axios automatically converts the response to JSON – you don’t need to call .json() manually.

• It has built-in support for request and response interceptors.

• It makes it easier to send headers, handle errors, and work with non-GET requests (POST, DELETE, and so on).

First, install Axios in your project via the terminal:

npm install axios

Import the necessary hooks and Axios and make the API call inside useEffect.

import { useEffect, useState } from 'react';
import axios from 'axios';

function App() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    axios.get('https://jsonplaceholder.typicode.com/users')
      .then(response => setUsers(response.data);
      // response.data contains the parsed JSON from the API.
      // setUsers(data) updates the React state with that JSON and stores it in state so you can access it.
  }, []);

  return (
    <div className="p-6 max-w-4xl mx-auto">
      <h1 className="text-2xl font-bold mb-4">User List (using Axios)
      </h1>
      <ul className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
        {users.map(user => (
          <li key={user.id} className="bg-white shadow p-4 rounded-xl">
            <h2 className="text-lg font-semibold">{user.name}</h2>
            <p className="text-sm text-gray-600">{user.email}</p>
            <p className="text-sm text-gray-600">{user.company.name}</p>
          </li>
        ))}
      </ul>
    </div>
//Map through the stored data in the state and display the contents
// in a list and access the properties from the data(user.name)
  );
}

export default App;

How to Handle Loading and Error States

When working with data fetching in React, things don't always go perfectly. Sometimes data takes time to arrive and other times the request fails. Loading and Error states come in handy because they give you feedback and make it both user and developer friendly.

What is a Loading State?

A loading state is used to show that data is being fetched. Without it, users might not know what is happening and think the request did not go through or the app isn't working. You typically use a boolean to track this.

What is an Error State?

An error state tells you something went wrong – maybe the API is down, or the URL was incorrect. Catching and displaying these errors helps you debug faster and gives users clear feedback.

Code Snippet:

Here's how you might add loading and error handling to a basic fetch() request:

const [users, setUsers] = useState([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);

useEffect(() => {
  fetch('https://jsonplaceholder.typicode.com/users')
    .then(res => {
      if (!res.ok) throw new Error('Network response was not ok');
      return res.json();
    })
    .then(data => {
      setUsers(data);
      setLoading(false);
    })
    .catch(err => {
      setError(err.message);
      setLoading(false);
    });
}, []);

if (loading) return <p>Loading...</p>;
if (error) return <p>Error: {error}</p>;

This gives you a smoother user experience and makes your app more reliable.

How to Keep Your API Keys Safe

If you're using an API that requires a key, it's critical to keep that key secure. Never hardcode your API keys directly into your React components or push them to public repositories. Instead, store them in a .env file at the root of your project(the same directory as your package.json file). In your .env file do this:

VITE_API_KEY=your_actual_key_here

To access it in your app, use:

const apiKey = import.meta.env.VITE_API_KEY;

You can then use this key in your API requests. Here's how you would include it in the Axios example:

axios.get(`https://api.example.com/data?apikey=${apiKey}`)
  .then(response => {
    setUsers(response.data);
    setLoading(false);
  })
  .catch(error => {
    setError(error.message);
    setLoading(false);
  });

Note: In Vite, all environment variables must start with VITE_ to be accessible in the browser. Make sure to add .env to your .gitignore file so it doesn’t get pushed to GitHub.

Hiding your key helps prevent exposing your it to the public, especially if your project is shared on GitHub or deployed online.

Why this is important:

• Exposed keys can be abused, leading to overages or bans from the API provider

• You could lose access or rack up charges depending on the service

• In secure apps, exposed keys can be a major security vulnerability

Always treat your keys like passwords. If a key does get exposed, revoke it and generate a new one from your API provider’s dashboard.

Fun Public APIs to Practice With

Here are some fun and free APIs you can use to build practice projects.:

1. JSONPlaceholder: Fake data for testing: users, posts, comments, todos. No key required.

2. The Dog API: Get random pictures, breed info, and search by breed. Requires a free API key.

3. The Cat API: Just like the Dog API, but for cats. Great for image-heavy apps. Free API key.

4. PokeAPI: Fetch detailed Pokémon data. Great for cards, search filters, or games. No key required.

5. TMDB API: Get movie data, trending shows, cast details, posters, and more. Requires a free API key from TMDB( You can clone popular streaming sites with this).

6. REST Countries API: Retrieve country names, capitals, regions, flags, and populations. No API key required.

7. Bored API: Get random activity suggestions for when you're bored. No key required.

8. JokeAPI: Fetch jokes by category or type (safe for work, programming, dark humor). No key needed.

9. Rick and Morty API: Explore characters, locations, and episodes. Perfect for fans. No key required.

10. NASA APIs: Explore images, astronomy data, and space facts. Requires free API key from NASA.

Play around with different data formats, add filters or search, and combine multiple APIs into one project. It's great practice for real-world app development.

Conclusion

What you've just built is the foundation of countless real-world applications. The ability to fetch, manage, and display data from APIs is essential in web development.

From here, you can extend this app to:

• Add search or filter functionality

• Paginate the results

• Display details on a separate page

As you continue to grow as a developer, the patterns you practiced here will show up again and again. Mastering them now sets you up for success later.

In the context of Flutter, a framework that enables cross-platform development, understanding how to secure mobile APIs is essential – not only for maintaining user trust but also for safeguarding sensitive business data.

In this article, we’ll explore common API vulnerabilities in mobile applications, particularly Flutter apps, and outline practical strategies to mitigate these risks.

Table of Contents

• Why API Security Matters in Mobile Apps

• Project Setup Example:

• Common Vulnerabilities in Flutter Apps

• Example: Secure API Call in Flutter

• Best Practices for Securing APIs in Flutter Apps

• Security Checklist for Flutter Developers

• Additional Considerations

• Conclusion

• References

Securing API keys in a Flutter application is essential to prevent unauthorized access to sensitive resources. API keys are often used for authentication with external services – but if they’re exposed, they can lead to security vulnerabilities.

In this guide, we will discuss how to securely store and manage API keys using Firebase Remote Config, Flutter Secure Storage, AES encryption, and device-specific identifiers.

There are several ways to manage API keys securely, including:

• CI/CD Solutions: Services like Codemagic, CircleCI, and GitHub Actions allow you to store API keys as environment variables to keep them out of your codebase.

• Backend Storage: Keeping API keys on a backend server and fetching them dynamically is another secure approach.

• Keystore & Keychain: On Android and iOS, API keys can be securely stored using the device's built-in keystore mechanisms.

• Encrypted Storage: Using encrypted local storage solutions to save API keys on the device.

Why API Security Matters in Mobile Apps

APIs serve as the bridge between mobile applications and backend services. While they enable dynamic experiences, such as fetching user data, processing payments, and managing real-time content, they also become a major attack vector if left unsecured.

Mobile applications, unlike web apps, are distributed in compiled form (for example, APKs). These can be decompiled to reveal logic, endpoints, and sometimes even secrets like API keys.

Attackers may reverse engineer APKs, intercept traffic using proxy tools like Burp Suite, or abuse API endpoints via emulators or scripts. This can lead to data breaches, unauthorized data manipulation, or service disruption.

Publicly exposing API keys in your Flutter application can lead to unauthorized access and potential abuse. This can result in quota exhaustion, service disruptions, or even security breaches. Using Firebase Remote Config, encryption, and secure local storage, we can keep API keys safe.

Project Setup Example:

For this example, we will focus on using Firebase Remote Config to securely retrieve API keys, encrypt them before storing them locally, and decrypt them when needed.

We will structure an implementation using the following:

• remote_config.dart: Handles fetching and encrypting API keys.

• global_config.dart: Initializes Firebase, loads environment variables, and ensures API keys are available.

• main.dart: Starts the application and initializes configurations.

• app_strings.dart: Stores constant values used throughout the project.

Step 1: Setting Up Environment Variables

Create a .env file in your Flutter project root directory and define your encryption key:

ENCRYPTION_KEY=32-character-secure-key-here

Add flutter_dotenv to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  encrypt: ^5.0.3
  flutter_dotenv: ^5.2.1
  device_info_plus: ^11.3.0
  firebase_remote_config: ^5.4.0
  flutter_secure_storage: ^9.0.0

Run:

flutter pub get

Step 2: Secure Storage and Encryption

app_strings.dart

Define constants used throughout the project:

class AppStrings {
  static const String ENCRYPTION_KEY = "ENCRYPTION_KEY";
  static const String DEVICE_ID = "DEVICE_ID";
  static const String YOU_VERIFY_API_KEY = "YOU_VERIFY_API_KEY";
  static const String GEMINI_API_KEY = "GEMINI_API_KEY";
}

remote_config.dart

Handles secure retrieval and storage of API keys using AES encryption. This is a big one, so I’ll break down each part after the code block:

import 'dart:io';
import 'package:device_info_plus/device_info_plus.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:firebase_remote_config/firebase_remote_config.dart';
import '../constants/app_strings.dart';
import '../../../domain/models/custom_error/custom_error.dart';
import 'package:encrypt/encrypt.dart' as encrypt;
import 'package:flutter_dotenv/flutter_dotenv.dart';

class RemoteConfig {
  static final FlutterSecureStorage _storage = FlutterSecureStorage();
  static encrypt.Encrypter? _encrypter;

  // Initialize AES encryption
  static Future<void> initializeEncrypter() async {
    encrypt.Key key = await _generateEncryptionKey();
    _encrypter = encrypt.Encrypter(encrypt.AES(key, mode: encrypt.AESMode.cbc));
  }

  static encrypt.Encrypter getEncrypter() {
    if (_encrypter == null) {
      initializeEncrypter();
    }
    return _encrypter!;
  }

  // Generate a secure encryption key using env variable and device ID
  static Future<encrypt.Key> _generateEncryptionKey() async {
    String envKey = dotenv.env[AppStrings.ENCRYPTION_KEY] ?? "default_secure_key";
    String deviceId = await _getDeviceId();
    String combinedKey = (envKey + deviceId).substring(0, 32);
    return encrypt.Key.fromUtf8(combinedKey);
  }

  // Fetch device ID and store it securely
  static Future<String> _getDeviceId() async {
    String? storedDeviceId = await _storage.read(key: AppStrings.DEVICE_ID);

    if (storedDeviceId != null) {
      return storedDeviceId;
    }

    DeviceInfoPlugin deviceInfo = DeviceInfoPlugin();
    String deviceId;

    if (Platform.isAndroid) {
      AndroidDeviceInfo androidInfo = await deviceInfo.androidInfo;
      deviceId = androidInfo.id;
    } else if (Platform.isIOS) {
      IosDeviceInfo iosInfo = await deviceInfo.iosInfo;
      deviceId = iosInfo.identifierForVendor ?? "fallbackDeviceId";
    } else {
      deviceId = "fallbackDeviceId";
    }

    await _storage.write(key: AppStrings.DEVICE_ID, value: deviceId);
    return deviceId;
  }

  // Fetch and encrypt API keys
  static Future<void> fetchApiKey({required String apiKeyName}) async {
    String key = '';
    try {
      final remoteConfig = FirebaseRemoteConfig.instance;
      await remoteConfig.setConfigSettings(
        RemoteConfigSettings(
          fetchTimeout: const Duration(seconds: 10),
          minimumFetchInterval: const Duration(seconds: 10),
        ),
      );
      await remoteConfig.fetchAndActivate();
      key = remoteConfig.getString(apiKeyName);
    } catch (e) {
      if (kDebugMode) {
        print(e);
      }
      throw CustomError(
        errorMsg: "ERROR Retrieving $apiKeyName (${e.toString()})",
        code: "configuration_error",
        plugin: "",
      );
    }

    final iv = encrypt.IV.fromSecureRandom(16);
    final encryptedKey = _encrypter?.encrypt(key, iv: iv).base64;

    await _storage.write(key: apiKeyName, value: encryptedKey);
    await _storage.write(key: "${apiKeyName}_iv", value: iv.base64);
  }

  static final Map<String, String> _decryptedKeysCache = {};

  // Retrieve and decrypt stored API keys
  static Future<String?> getApiKey({required String key}) async {
    if (_decryptedKeysCache.containsKey(key)) {
      return _decryptedKeysCache[key];
    }

    try {
      final encryptedKey = await _storage.read(key: key);
      final ivString = await _storage.read(key: "${key}_iv");

      if (encryptedKey != null && ivString != null) {
        final iv = encrypt.IV.fromBase64(ivString);
        final encrypted = encrypt.Encrypted.fromBase64(encryptedKey);
        final decryptedKey = _encrypter?.decrypt(encrypted, iv: iv);

        _decryptedKeysCache[key] = decryptedKey!;
        return decryptedKey;
      }
    } catch (e) {
      throw CustomError(
        errorMsg: "ERROR Retrieving $key (${e.toString()})",
        code: "configuration_error",
        plugin: "",
      );
    }

    return null;
  }
}

This RemoteConfig class securely fetches, encrypts, stores, and retrieves sensitive API keys using Firebase Remote Config, AES encryption, secure storage, and device-specific information.

Here's a breakdown of what’s going on:

1. Dependencies and Imports

• dart:io: For platform-specific checks (Android, iOS).

• device_info_plus: To get a unique device identifier.

• flutter_secure_storage: For secure local key-value storage.

• firebase_remote_config: To fetch API keys or configurations from Firebase.

• encrypt: For AES encryption and decryption.

• flutter_dotenv: To read environment variables.

• CustomError: A custom error model used for error handling.

• AppStrings: Presumably holds constant strings like keys.

2. Class Properties

static final FlutterSecureStorage _storage = FlutterSecureStorage();
static encrypt.Encrypter? _encrypter;

• _storage: For securely storing encrypted keys and IVs.

• _encrypter: Used to encrypt and decrypt data using AES.

3. initializeEncrypter()

static Future<void> initializeEncrypter() async

• Sets up the AES encryptor using a combination of a .env key and the device ID to generate a 32-byte key.

• Uses AES CBC mode.

4. getEncrypter()

static encrypt.Encrypter getEncrypter()

• Returns the existing encryptor or calls initializeEncrypter() if it's not yet initialized.

5. _generateEncryptionKey()

static Future<encrypt.Key> _generateEncryptionKey()

• Combines an environment variable (ENCRYPTION_KEY) and the device ID to produce a 32-character key.

• Returns an AES key (encrypt.Key.fromUtf8).

6. _getDeviceId()

static Future<String> _getDeviceId()

• Checks if a device ID is already securely stored. If not, gets it from the device (Android: androidInfo.id, iOS: identifierForVendor).

• Stores the device ID securely for future use.

7. fetchApiKey()

static Future<void> fetchApiKey({required String apiKeyName})

• Fetches the specified API key from Firebase Remote Config.

• Encrypts the key using AES and a random IV (initialization vector).

• Stores both the encrypted key and the IV securely.

8. getApiKey()

static Future<String?> getApiKey({required String key})

• Retrieves and decrypts the encrypted API key.

• If already decrypted and cached in memory, returns it immediately.

• Otherwise:

  • Reads the encrypted key and IV from secure storage.

  • Decrypts the key and returns it.

  • Caches the decrypted result in _decryptedKeysCache.

9. Error Handling

Custom CustomError exceptions are thrown if Firebase fetch or decryption fails.

This class is built to:

• Securely fetch API keys from Firebase.

• Encrypt them using a key tied to both an environment variable and the specific device.

• Store them locally in an encrypted form.

• Allow retrieval and decryption with in-memory caching to minimize processing overhead.

Step 3: Global Initialization

global_config.dart

Handles Firebase initialization, dependency injection, and API key retrieval:

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:injectable/injectable.dart';
import 'remote_config.dart';
import 'app_strings.dart';

class GlobalConfig {
  static Future<void> fetchRequiredApiKeys() async {
    final apiKeys = [
      AppStrings.YOU_VERIFY_API_KEY,
      AppStrings.GEMINI_API_KEY,
    ];
    for (final keyName in apiKeys) {
      await RemoteConfig.fetchApiKey(apiKeyName: keyName);
    }
  }

  static Future<void> initConfig() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    await dotenv.load(fileName: ".env");
    await RemoteConfig.initializeEncrypter();
    await fetchRequiredApiKeys();
  }
}

Step 4: Utilizing the API Key in UI

main.dart

Initializes the application:

import 'package:flutter/material.dart';
import 'global_config.dart';

Future<void> main() async {
  await GlobalConfig.initConfig();
  runApp(MyApp());
}

Step 5: Fetching API Key in Widget

String apiKey = "";

@override
void initState() {
  super.initState();
  fetchAPIKey();
}

void fetchAPIKey() async {
  try {
    final key = await RemoteConfig.getApiKey(key: AppStrings.GEMINI_API_KEY) ?? "";
    setState(() {
      apiKey = key;
    });
  } catch (e) {
    print("Error fetching API key: $e");
  }
}

Common Vulnerabilities in Flutter Apps

1. Hardcoding Secrets

Storing API keys or secrets in the codebase (even in .env or .dart files) is one of the most dangerous mistakes. Tools like apktool can extract these secrets easily from the compiled binary.

Avoid this:

// Do not hardcode keys
const apiKey = 'YOUR_SECRET_API_KEY';

Hardcoding secrets is unsafe because when the APK is reverse-engineered, anyone can read those values and misuse your APIs.

Use secure storage instead:

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final storage = FlutterSecureStorage();
await storage.write(key: 'api_key', value: 'your_api_key');
final apiKey = await storage.read(key: 'api_key');

Using flutter_secure_storage stores secrets securely in platform-specific secure storage mechanisms like Android's Keystore or iOS's Keychain.

2. Lack of SSL/TLS Enforcement (MITM Attacks)

A Man-in-the-Middle (MITM) attack occurs when an attacker intercepts and potentially alters communication between two parties. This is especially dangerous in unsecured HTTP connections, as sensitive information like login credentials and API keys can be stolen or modified.

How SSL/TLS Secures Code:

Secure Sockets Layer (SSL) and Transport Layer Security (TLS) are cryptographic protocols that ensure encrypted communication between a client and a server. This prevents MITM attacks by ensuring that the data is encrypted and cannot be read or altered while in transit. The connection is established over HTTPS (which is HTTP over SSL/TLS).

Code Example to Enforce SSL/TLS:

import 'package:http/http.dart' as http;

void makeSecureRequest() async {
  final response = await http.get(Uri.parse('https://yourapi.com/endpoint'));

  if (response.statusCode == 200) {
    // Handle successful response
  } else {
    // Handle error
  }
}

In this case, making sure that the URL starts with https:// enforces the use of SSL/TLS for secure communication

3. Weak Authentication

Weak authentication methods are those that are easily guessed or bypassed, such as simple passwords, lack of multi-factor authentication, or weak hashing mechanisms.

Instead, you should use robust authentication methods like Firebase and OAuth.

• Firebase Authentication provides various authentication methods such as email/password login, Google sign-in, and phone number authentication. It is a secure and easy-to-implement solution.

• OAuth is a protocol that allows third-party services (like Google or Facebook) to securely authenticate users without exposing their password to your app. OAuth uses tokens for authorization, ensuring that user credentials are not compromised.

Use Firebase Auth or OAuth2:

import 'package:firebase_auth/firebase_auth.dart';

final FirebaseAuth _auth = FirebaseAuth.instance;
UserCredential userCredential = await _auth.signInWithEmailAndPassword(
  email: 'user@example.com',
  password: 'securePassword',
);
final token = await userCredential.user?.getIdToken();

Token-based authentication allows the backend to verify the identity of the user securely without relying on session cookies. Firebase Authentication handles token generation, validation, and expiration for you.

4. Insufficient Authorization Checks

Authorization checks are necessary to ensure that the authenticated user has the required permissions to perform certain actions. For example, an admin user may have access to all endpoints, while a regular user may only have access to limited resources.

How to Verify User Roles/Permissions:

On the server side, roles and permissions are typically stored in a database. When a user makes a request, the server checks their role and compares it against the required permissions for the requested resource.

Code Example:

// Assuming user roles are stored in Firestore
Future<bool> checkUserRole(String userId, String requiredRole) async {
  final userDoc = await FirebaseFirestore.instance.collection('users').doc(userId).get();
  final userRole = userDoc.data()?['role'];

  if (userRole == requiredRole) {
    return true;
  } else {
    throw CustomError(errorMsg: 'User does not have the required role');
  }
}

Authorization ensures the user is not only authenticated but also has the rights to perform specific actions.

5. Exposed Endpoints and Metadata

Exposing Swagger documentation or test endpoints in production can allow attackers to easily discover vulnerabilities in your API. It provides them with detailed information about the structure and capabilities of your API, which can be exploited.

How to Secure with Route Guards:

A route guard can prevent unauthorized access to sensitive routes, ensuring that only authenticated and authorized users can access certain endpoints.

void checkRouteAccess(String route) {
  if (!isUserAuthenticated()) {
    throw CustomError(errorMsg: 'User not authorized');
  }
}

Avoid this:

• Don't deploy Swagger docs without authentication

• Use route guards for admin/dev routes

• Strip debug symbols and logs in production builds

Example: Secure API Call in Flutter

Here’s a simple example using Dio, a powerful HTTP client for Dart, to securely call an API with token-based authentication and HTTPS:

import 'package:dio/dio.dart';
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final dio = Dio();
final storage = FlutterSecureStorage();

Future<void> fetchSecureData() async {
  final token = await storage.read(key: 'auth_token');

  dio.options.headers['Authorization'] = 'Bearer $token';

  try {
    final response = await dio.get('https://yourapi.com/secure-endpoint');
    print(response.data);
  } catch (e) {
    print('API call failed: $e');
  }
}

This example illustrates how to include an authorization token in your request header and securely make an HTTPS request using dio. Dio also supports interceptors, retries, and advanced options like certificate pinning.

Best Practices for Securing APIs in Flutter Apps

Always Use HTTPS

Avoid plain HTTP at all costs. Use HTTPS to encrypt data in transit.

final response = await http.get(Uri.parse('https://api.secure.com/data'));

Implement OAuth2 or Firebase Auth

Use modern authentication packages like firebase_auth or oauth2_client. These offer secure, token-based authentication with built-in session and refresh token management.

Use Firebase App Check

Prevents abuse of your backend by verifying the legitimacy of the client app.

await FirebaseAppCheck.instance.activate(
  webRecaptchaSiteKey: 'your-site-key',
);

Secure Storage of Sensitive Data

Use flutter_secure_storage to safely store tokens and secrets locally.

Obfuscate Dart Code

Obfuscation makes your Dart code harder to reverse-engineer. You can do this by renaming classes, methods, and variables into meaningless names.

flutter build apk --obfuscate --split-debug-info=build/symbols

This command strips debug information and renames classes/functions, making it harder for attackers to understand your compiled code.

Use Rate Limiting and Throttling

Protect backend APIs from abuse by rate-limiting requests. Implement server-side rate-limiting using API Gateway tools or middleware libraries. Here’s a tutorial that’ll teach you more about this technique.

Set Up Logging and Monitoring

Use tools like Firebase Crashlytics or Sentry to track errors and suspicious activity.

FirebaseCrashlytics.instance.recordError(e, stackTrace);

API Gateway and WAF

Use API management layers like Google Cloud Endpoints or AWS API Gateway along with Web Application Firewalls (WAF) to control and filter traffic.

Security Checklist for Flutter Developers

• Use HTTPS for all communications

• Never hardcode secrets or credentials

• Use token-based authentication (OAuth2, Firebase Auth)

• Validate tokens on both client and server

• Obfuscate and minify code before production

• Securely store sensitive data using flutter_secure_storage

• Enable Firebase App Check or equivalent

• Use API Gateways and WAFs for traffic filtering

• Monitor usage logs and set up alerts for anomalies

• Implement rate limiting to prevent abuse

Additional Considerations

Certificate Pinning:

Certificate pinning is a technique used to ensure that the app only communicates with a trusted server by comparing the server's certificate against a pre-stored certificate or public key. This prevents attackers from using fraudulent certificates.

Example: Certificate Pinning in Dio

class CertPinningInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
    final context = SecurityContext(withTrustedRoots: false);
    final certBytes = (await rootBundle.load('assets/certs/myserver.cer')).buffer.asUint8List();
    context.setTrustedCertificatesBytes(certBytes);

    final client = HttpClient(context: context);
    client.badCertificateCallback = (X509Certificate cert, String host, int port) {
      final serverSha = sha256.convert(cert.der).toString();
      const expectedSha = 'your_cert_sha256_fingerprint';
      return serverSha == expectedSha;
    };

    (options.extra['httpClientAdapter'] as DefaultHttpClientAdapter?)
        ?.onHttpClientCreate = (_) => client;

    handler.next(options);
  }
}

• SecurityContext(withTrustedRoots: false): Starts with an empty trust store, meaning no system CAs are trusted by default.

• setTrustedCertificatesBytes: Loads your own server’s certificate from local assets and sets it as the only trusted certificate.

• HttpClient.badCertificateCallback: Compares the server’s certificate SHA-256 fingerprint against a known good value. If they match, the request proceeds.

• onHttpClientCreate: Replaces the default Dio HTTP client with the custom client configured for pinning.

This ensures that your app will only accept HTTPS connections from your own trusted server, protecting users from certificate spoofing or MITM attacks.

TTL and Token Rotation:

Time-to-Live (TTL) is a security measure that ensures tokens automatically expire after a defined period. This limits the duration a token can be used, reducing the attack surface if it’s compromised.

Token Rotation enhances security further by issuing a new refresh token every time the existing one is used to request a new access token. The previous refresh token is then invalidated. This prevents replay attacks where an attacker might attempt to reuse a stolen refresh token.

Real-World Token Lifecycle:

1. Access Token:

   • TTL: Short (for example, 15 minutes)

   • Purpose: Used to authenticate and authorize API requests

   • Behavior: Expires quickly to minimize risk if exposed

2. Refresh Token:

   • TTL: Longer (for example, 7 days)

   • Purpose: Used to request new access tokens without requiring the user to log in again

   • Rotation: A new refresh token is issued with each use

Here’s an example Implementation (Dart-like Pseudo-code):

Generate an access token (15-minute TTL):

String generateAccessToken(String userId) {
  final expiry = DateTime.now().add(Duration(minutes: 15));
  return createJwtToken(userId: userId, expiresAt: expiry);
}

Then generate a refresh token (7-day TTL):

String generateRefreshToken(String userId) {
  final expiry = DateTime.now().add(Duration(days: 7));
  return createSecureRandomToken(userId: userId, expiresAt: expiry);
}

Refresh the endpoint with rotation:

Map<String, String> refreshAccessToken(String refreshToken) {
  if (isValidRefreshToken(refreshToken)) {
    final userId = getUserIdFromRefreshToken(refreshToken);

    // Invalidate old refresh token
    invalidateRefreshToken(refreshToken);

    // Rotate tokens
    final newRefreshToken = generateRefreshToken(userId);
    final newAccessToken = generateAccessToken(userId);

    return {
      'accessToken': newAccessToken,
      'refreshToken': newRefreshToken,
    };
  } else {
    throw CustomError(errorMsg: 'Invalid or expired refresh token');
  }
}

Why this matters:

• Mitigates long-term exposure: Tokens automatically expire, reducing risk.

• Prevents replay attacks: A rotated refresh token cannot be reused if intercepted.

• Enhances session security: Even if a token is stolen, it becomes useless quickly.

Backend Validation:

Backend validation ensures that sensitive data, like API keys or JWT tokens, is checked on the server side, preventing tampering from malicious users.

Never trust the client. Always re-validate all sensitive operations and user roles on the backend.

Example:

void validateToken(String token) {
  if (isTokenExpired(token)) {
    throw CustomError(errorMsg: 'Token expired');
  }
}

• validateToken(String token): A function that takes a user's token as input.

• isTokenExpired(token): A hypothetical function that checks whether the token has expired (e.g., by decoding the token and checking its expiry timestamp).

• throw CustomError(...): If the token is expired, an error is thrown — in this case, a CustomError with a message saying 'Token expired'.

Why this matters:

• Tokens can be stolen or manipulated on the client side, so trusting them blindly is dangerous.

• Backend checks like this help enforce server-side control over user authentication and session validity.

• Even if a user tampers with client-side code, they can't bypass this server-side validation.

Use Security-focused Tools like OWASP ZAP/Burp Suite/Postman:

Use tools like OWASP ZAP, Burp Suite, and Postman to manually and automatically test your API endpoints for vulnerabilities.

• OWASP ZAP: Used for penetration testing, finding vulnerabilities like XSS, SQL Injection, and so on.

• Burp Suite: Another tool for testing security vulnerabilities in web apps.

• Postman: Can be used for testing API endpoints and ensuring secure communications by adding necessary headers like Authorization.

Conclusion

Securing mobile APIs is a foundational requirement in modern app development. For Flutter developers, this means going beyond building beautiful UIs to ensuring the underlying API infrastructure is resilient against threats. The risks of exposed endpoints, leaked secrets, and insecure communication are very real, but preventable.

Security is about proactive defense, and you should make it a core part of your development workflow. With consistent practices, regular audits, and attention to detail, you’ll protect both your users and your product from unnecessary risks. Flutter provides the flexibility and power to build fast, cross-platform apps – so don’t let poor API security undermine that potential.

By following the best practices outlined in this article, such as using HTTPS, implementing proper authentication and authorization, securely storing credentials, and leveraging tools like Firebase App Check, you can significantly reduce your app’s attack surface.

Remember: effective security starts with a mindset. It’s not just a one-time setup, but an ongoing process of vigilance, testing, and improvement.

References

• OWASP Mobile Security Project

• OWASP API Security Top 10

• Android Security Best Practices

• Flutter Secure Storage - pub.dev

• Encrypt Package - pub.dev

• Firebase Remote Config - Firebase Docs

• Device Info Plus - pub.dev

• Flutter dotenv - pub.dev

• Injectable for Dependency Injection - pub.dev

• Flutter Fire (Firebase Initialization) - Firebase Docs