DEV Community: lou

[Boost]

lou — Fri, 06 Mar 2026 15:48:22 +0000

Understanding the Agentic AI Ecosystem: Prompts, Memory, RAG, MCP, and Tool-Using LLMs

lou ・ Mar 5

#rag #llm #mcp #genai

[Boost]

lou — Thu, 05 Mar 2026 21:47:06 +0000

Understanding the Agentic AI Ecosystem: Prompts, Memory, RAG, MCP, and Tool-Using LLMs

lou ・ Mar 5

#rag #llm #mcp #genai

Understanding the Agentic AI Ecosystem: Prompts, Memory, RAG, MCP, and Tool-Using LLMs

lou — Thu, 05 Mar 2026 10:10:40 +0000

Gen AI is a type of AI that’s capable of generating new data like images, text, audio, etc, based on the training data.

The main idea is: you use a large amount of data, for example images of children, and you train a model on it. Once it’s trained, you give it a prompt (you ask it a question). In that prompt you can ask it, for example: “generate for me a new image of a child, inspired by the training data”. And now these models are capable of understanding prompts and generating what we request.

When we speak about AI, we basically have two big families:

discriminative AI
generative AI

Discriminative AI

Discriminative AI is what we know traditionally. Like when you build a classification model: you will use a dataset that contains dogs and cats, you label the images, and you train the model so it can predict if the animal is a cat or a dog.

This is done with neural networks (réseaux de neurones): you train it on data where it learns the mapping between input and output. Once training is done, when you give it a new image, it predicts the label.

And we can also do regression (predicting a continuous value instead of a class).

Generative AI

But with Gen AI, instead of training a model only to classify, you train it on a large dataset (cats, dogs, everything), and then you can ask it prompts like: “generate a new dog next to a cat”. The image is new, it has never been in the dataset, but it follows the patterns the model learned during training.

So Gen AI is a type of AI capable of generating new data based on a large dataset provided during training.

A quick timeline (why everything exploded)

In 2014, generative AI had a big milestone with GANs (Generative Adversarial Networks), which became popular for image generation. And you probably know this famous website that generates faces of people who don’t exist: thispersondoesnotexist. (This kind of thing is based on GAN-style approaches.)

Then in 2017, Google researchers published Attention Is All You Need, which introduced the Transformer architecture and self-attention. This is one of the main reasons why language models became so powerful for NLP (Natural Language Processing). From there, everything accelerated.

In 2018, Google released BERT (Transformer-based).
Then OpenAI built the GPT line (Generative Pre-trained Transformer), and we started seeing large language models becoming mainstream.

Later, the big public explosion came with ChatGPT (and especially the versions that made people realize “wait… it actually understands what I mean”). After that we got a crazy wave: GPT-4, Gemini, LLaMA, Mistral, DeepSeek, and many others. Now we have models that can generate text, images, audio, and even video.

So what’s important for us is to understand these different model types we can use:

LLMs that take text in and give text out (classic chat models)
multimodal models that take text + image and can answer about images
models that generate images from text (like DALL·E, Stable Diffusion)
OCR apps (Optical Character Recognition) where we extract text from images

Why the AI jump happened (3 reasons)

1) Transformers

Transformers made it possible to understand language syntax + semantics much better than older approaches. That’s why models can answer complex questions and follow instructions.

2) Data

We have a massive amount of data available (web-scale). That’s what enabled training large models.

3) Compute (GPUs / TPUs / cloud)

Transformers are heavy: it’s a lot of matrix computation, and it takes time. So we needed acceleration. GPUs (like NVIDIA) are perfect for parallel computation: many cores, parallel operations, faster training.

That’s why companies training LLMs need GPUs (or TPUs like Google’s). And because of cloud computing, we can access high-performance computing (HPC) without owning a full data center.

And these are the main reasons behind the jump in AI.

Prompts and prompt engineering

You have LLM models and you want to create an app. You build the app, and your app needs to ask the LLM.

So you send a prompt. The prompt is basically the question/instructions you send to the model. The model understands the prompt and generates a response, and the response is sent back to your app.

Using Gen AI in production means doing prompt engineering.

There are two things:

what is a prompt
what is prompt engineering

Prompts

A prompt is a group of instructions (text) that you send to an LLM to do a certain task. The way you ask the question changes the outcome. There are best practices.

Prompt engineering

Prompt engineering is about:

creating prompts
reviewing prompts (yes there are metrics and evaluation techniques)
deploying prompts (building apps that use these prompts to solve a specific domain problem)

Prompt structure: system message + user message (+ examples)

A prompt usually has 3 parts:

1) System message

This is the instruction that explains to the model the role + the task + constraints.

For example for sentiment analysis, the system message can assign a role:

“You are an analyst. Deduce if the sentiment is positive, neutral, or negative. Output JSON.”

This system message is usually fixed. It’s the part you design and improve.

2) Few-shot examples (optional)

Examples of input/output to guide the model.

For example:

“I’m really satisfied” → {"sentiment":"positive"}
“I am not a fan” → {"sentiment":"negative"}
“I will get back to you” → {"sentiment":"neutral"}

These examples make the model more consistent and more precise.

If you give:

0 examples: zero-shot
1 example: one-shot
more than 1: few-shot

In general, the more relevant examples you give, the more stable the output becomes (within the limit of the context window).

3) User message

This is the user input. The user writes a comment/question, and your app injects it into the prompt.

So it’s like:
“Here are the instructions (system message), here are examples (optional), now answer the user question.”

Params: temperature, max tokens, context window

When we send a prompt to an LLM, we also send parameters. The most common ones:

Temperature

Depends on the task.

If you want precision (classification, extraction, strict formatting), set temperature close to 0.
- Same question multiple times gives nearly the same answer.
If you want creativity (story, brainstorming), temperature closer to 1.
- Same question gives different variations.

Example:

reading blood test results → temperature 0
fantasy short story → temperature close to 1

Max tokens + tokenization

LLMs don’t see text like humans. They tokenize it.

OpenAI tokenizer:
https://platform.openai.com/tokenizer

The main idea: in NLP we create a vocabulary (dictionary) of tokens. Tokenization can be simple (split by spaces), but modern tokenizers are more advanced. Each LLM uses its own tokenizer. In Python, OpenAI has tiktoken.

So text becomes tokens, each token becomes an ID, and the model works on sequences of token IDs.

This matters because billing is often based on token count, and also because the model has a maximum limit: the context window (the maximum tokens it can accept in one prompt). That’s why in prompt engineering we also try to economize tokens.

Chain-of-thought prompting (and agents)

Another concept people talk about is helping the model “think step by step”. This idea is heavily related to agentic systems (we’ll get there).

Experiment locally with Ollama (open source)

To experiment, let’s install Ollama:

curl -fsSL https://ollama.com/install.sh | sh

Once installed, you can call the local API at port 11434. More on tool calling here:
Ollama tool calling docs

We will use the qwen3 model.

Run:

ollama run qwen3

Then you can send it a request using your API client like so:

Fine-tuning vs RAG

Sometimes few-shot prompting isn’t enough. In that case, people do fine-tuning: you take a base model, and you retrain it on your own dataset (domain-specific input/output pairs).

Example in a pharmaceutical context: you want the AI to know what certain meds are used for. You prepare data like this:

{
  "messages": [
    {
      "role": "user",
      "content": "Patient takes Doliprane 1000 mg for fever and headache. What medication is this?"
    },
    {
      "role": "assistant",
      "content": "Doliprane contains paracetamol and is commonly used to treat fever and mild to moderate pain."
    }
  ]
}

That gives you a more specialized model.

Fine-tuning is expensive because you are updating model weights (parameters). There are techniques like LoRA where you don’t fully modify the base weights, you add lightweight adapters (additional matrices) so the base model stays intact and you still get specialization with less compute.

RAG (Retrieval-Augmented Generation)

Instead of changing the model, you can keep the model as-is and provide it with relevant context at question time.

In an enterprise system (E/S), you have documents that are not structured: PDFs, text files, sometimes images, audio, JSON, etc.

Because the LLM has a context window, you can’t just dump millions of pages. So we split documents into chunks (paragraphs, pages, sections). Then we transform these chunks into vectors using an embedding model.

Each chunk becomes:

a vector (numbers representing semantic meaning)
plus metadata (document name, page number, etc)

We store vectors in a vector store / database (many DBs support vector fields now).

Then when the user asks a question:

the question is embedded into a vector (same embedding model)
we do semantic search (similarity search) against the chunk vectors
we retrieve the most relevant chunks = the context
we send to the LLM: system message + context + user question
the LLM answers using only that context

This is why similarity metrics matter. A classic one is cosine similarity: we compare vector directions. If the cosine is close to 1, vectors are similar (meaning is close). Databases like pgvector allow vector fields and similarity queries.

So RAG is: non-structured data → chunks → embeddings → vector DB → retrieve context → answer grounded in context.

And to reduce hallucinations, in the system message for RAG we often say something like:
“Answer using the provided context only. If the answer is not in the context, respond with ‘I don’t know’.”

A lot of enterprise systems use RAG to create internal chatbots. And you can also do multimodal RAG.

Multimodal RAG (text + audio + image + video)

How does it work with different modalities?

For audio/video: usually you do speech-to-text transcription first, then chunk the text, embed it, and store the vectors.
For images: you can either:
- extract text with OCR (if the image contains text), then embed,
- or generate a textual description/caption for the image with a vision-capable model, then embed that description.

So the vector DB still stores vectors representing semantic meaning, and the metadata helps you locate the source (document, page, timestamp, file name, etc). When you retrieve context, you also retrieve metadata, and you can instruct the LLM to cite where it came from.

This is why multimodal RAG is powerful: you can ask a question and the answer might come from a PDF, an audio lecture, an image, or a video transcript.

So now with RAG, an enterprise system can build an internal chatbot that responds based on internal data.

Agentic AI ecosystem

To explain how it works, we have a user who asks a question to an agentic app.

Suppose you want to ask the agent to send an email to the whole student body: tell them that on a certain date we will have exams, and before that there will be mock exams. In the email, you ask them to prepare specific topics, and to bring their machines on the mock exam dates.

The user doesn’t write the long detailed instructions. In a real product, the app prepares that. The user writes something simple like:

“Send the email to the students for the mock exams.”

When you send that to the agent, the agent is autonomous: it has a goal to achieve. But to make it do the right thing, you still need to describe the task clearly, so you give it a prompt.

The agent prompt usually has:

system message
optional few-shot examples
user message

In our example we don’t need few-shot examples. The system message is the detailed instruction text (written by the app / prompt engineering), and the user message is the short line: “send the email to the students for mock exams.”

The agent has a goal: automate a workflow. That’s why prompt engineering matters: writing prompts, reviewing prompts, testing them, deploying them.

Memory: because LLMs are stateless

LLMs are stateless. When an agent asks the LLM a question, the LLM is basically a function doing matrix computation: text becomes tokens, tokens become vectors internally, and it outputs a response.

If you ask the LLM:

Q1: “my name is lou” → it replies “hello lou”
then later you ask:
Q2: “what’s my name?” (without giving it Q1 again) → it will say “I don’t know” because it does not remember.

So if you want it to remember, you have to include the conversation history (or summary) in the prompt each time.

That’s why ChatGPT is not just “the LLM”. ChatGPT is an application (agentic app). It stores the conversation in a database, and every time you ask a question, it loads the memory and injects it into the prompt, then sends it to the LLM.

So memory = persistence. Session history stored in a DB. And you can store it in different ways:

raw conversation (full history)
summarized memory (semantic memory): store short summaries instead of full logs
structured memory tables, last-in-first-out, etc, depending on your design

So agents need memory, but they also need tools.

Tools: how the agent interacts with the world

What is a tool? It’s a function your app exposes to the agent to consult data or do actions.

Examples:

a tool to search PDFs using RAG (vector DB)
a tool to read Google Sheets
a tool to do web search
a tool to connect to IoT sensors
a tool to publish on social media
a tool to use Google Maps
a tool to send emails (Outlook / Gmail)

MCP: Model Context Protocol

Now the question is: how do we make it easy for an agent to use tools?

There is a protocol called MCP (Model Context Protocol). With MCP, you can create a server that exposes tools (functions) and gives the agent a standard way to discover and call them.

So when we create an agent, we give it the MCP server addresses, and the agent can use anything that is exposed there, even if tools are implemented with different technologies.

It’s like a new web service style for AI tools.

We spoke before about web services like SOAP, REST, GraphQL, and gRPC, in these posts:

SOAP: here
REST: here
GraphQL: here
gRPC

Now MCP helps create tool servers that are easily exploitable by agentic AI.

The flow in our example (mock exam email)

So we send the user request to the agent.

The agent asks the LLM: “respond to this request”. The LLM sees: “I need to send email to all students”, so it knows it needs:

the student list
the exam planning details
then draft the email
then send it

So the LLM tells the agent to call a tool to get the student list. The agent calls the tool (Google Sheets). It retrieves all student emails, and sends that back to the LLM as observations.

Then the LLM says: “I need the exam planning.” The agent calls the planning tool (another Google Sheet), retrieves the plan, and sends it back to the LLM.

Now the LLM generates the email content (subject + HTML body), and asks the agent to send it using the email tool (Outlook/Gmail). The agent sends it and confirms success.

This kind of app is what we call “agentic”, and a common pattern used here is ReAct:

Reasoning (LLM)
Action (tools)
Observations (environment/tool outputs)

What’s the principle?
At first you ask the agent. It reasons (using an LLM). The LLM decides the steps and the tools needed. The agent calls tools, retrieves data, sends observations back to the LLM, and the loop continues until the agent can complete the final action.

Multi-agent (agent-to-agent)

Sometimes one agent is not enough. So you can have specialized agents (each one has tools or skills for a specific domain). If an agent doesn’t have the right tools, it can communicate with another agent using an agent-to-agent protocol (often HTTP style).

So:

MCP helps access tools
agent-to-agent helps agents communicate between each other

And if you want voice interaction, you can also have real-time communication (RTC): user speaks in any language, a real-time model transcribes, sends the text to the agent, and then the agent responds (text-to-speech back).

That’s the full ecosystem: prompts + memory + tools + MCP + agents + ReAct loops, and optionally multi-agent collaboration.

[Boost]

lou — Sat, 28 Feb 2026 07:59:30 +0000

lou

Feb 14 '25

A Step by Step Guide to Building Lightning Fast APIs

#fastapi #python #pydantic #jwt

Comments

8 min read

[Boost]

lou — Sat, 28 Feb 2026 07:36:30 +0000

Part 1: Create a complete Microservices Architecture with Spring Boot, Spring Cloud, Eureka, Gateway, and OpenFeign

lou ・ Feb 11

#springcloud #springboot #java #microservices

[Boost]

lou — Sat, 28 Feb 2026 07:18:16 +0000

SOAP web service with JAX-WS

lou ・ Nov 20 '22

#javascript #webdev

Command Line Fundamentals: A Quick Reminder

lou — Sat, 21 Feb 2026 16:26:37 +0000

Reminder of Some Command Lines

The terminal is the application that you run that allows you to give commands to your computer.

The prompt is the text that you see right before the command you write in your terminal. You can customize it in your current session in zsh like this:

The tilde ~ means your home directory.

A command line is the text you write in your terminal after the prompt to give your computer a command.

GUI stands for Graphical User Interface. You can interact with it using your inputs (mouse, keyboard, etc.).

Navigation

cd

Every time you run:

cd

It moves you to your home directory.

If you want to move to a directory inside your home directory:

cd your_directory

If you have another directory inside it, you can go deeper:

cd child_directory

Now let’s say you want to go back, but not to home, just one level:

cd ..

If you want to go back two levels:

cd ../..

If you want to see the current directory you are in (the path), you run:

pwd

Creating Directories and Files

mkdir creates a new directory.
(In GUI you right click and choose "Create new folder".)

mkdir myfolder

To create a new file, you use the touch command.

It creates a new empty file in the current directory you are in.
So if you are in the home directory, the file will be created there.

touch myfile.txt

To list the files and directories you just created, you can run:

ls

It also takes options:

ls -l   # shows file permissions
ls -lh  # shows file sizes
ls -a   # shows hidden files

Variables and Echo

We can create variables like this:

dummyvar="my dummy variable"

echo is like the console log of the terminal.
It prints whatever you pass to it, whether it is a variable or a string.

echo $dummyvar

Shell Scripts (.sh)

If you want to run a list of commands, you can leverage shell scripts in .sh files.

The system will execute the commands one after another.

You can read and edit the content of a file using the nano editor:

nano myscript.sh

To save:

Ctrl + O

To exit:

Ctrl + X

To make your script file executable, you need to give it execution permission using chmod

chmod +x myscript.sh

Otherwise you will get a permission denied error:

Scheduling with Cron

We can schedule scripts to run at a specific time using cron.

You define when you want the script to run (for example, every day at 2 PM), and cron will execute it automatically.

Open the cron editor:

crontab -e

Cron takes 5 fields:

Minute  Hour  Day-of-month  Month  Day-of-week

Example:

5 14 * * 1

This means:

Every Monday at 2:05 PM, run the script.

Quick Exercise

Create a script file named myscript.

touch myscript.sh
nano myscript.sh

Add this inside:

echo "salam! this is my dummy script!"

Save and exit.

Make it executable:

chmod +x myscript.sh

Run the script:

./myscript.sh

You should see:

salam! this is my dummy script!

Reading the Content of a File

To read the content of our script file (or any other file), we use the cat command.

Example:

cat myscript.sh

This will display the content of the file directly in the terminal.

If your script contains:

echo "salam! this is my dummy script!"

Running:

cat myscript.sh

Will print:

echo "salam! this is my dummy script!"

If you want to see only the first 10 lines of the file, use:

head myscript.sh

If you want to see only the last 10 lines, use:

tail myscript.sh

You can also specify how many lines you want.

For example, to show only the first line:

head -n 1 myscript.sh

And to show the last 3 lines:

tail -n 3 myscript.sh

Moving and Renaming Files

Now let’s move our executable file into the directory myfolder that we created earlier with mkdir.

To move the file, we use the mv command:

mv myscript.sh myfolder

This moves myscript.sh into the directory myfolder.

If you run:

ls myfolder

You should see:

myscript.sh

Renaming a File

The mv command can also be used to rename a file.

For example:

mv myscript.sh

This does not move the file, it just renames it.

The syntax is always:

mv source destination

If the destination is a directory, it moves the file.
If the destination is a new name, it renames the file.

Removing a File

To remove a file, we use the rm command.

Example:

rm newscript.sh

This will delete the file newscript.sh.

If the file exists, it will be removed permanently.

If you want confirmation before deleting the file, use:

rm -i newscript.sh

Important:

The rm command deletes files permanently.
There is no recycle bin in the terminal so please be careful while playing with it.

Filtering Data

To selecting only the lines that match a condition, the most common command for filtering text is grep.

Example file:

cat data.txt

Content:

apple
banana
orange
apple
grape
Apple
apple
APPLE

Filter by Word

If we want to filter only the lines that contain apple:

grep apple data.txt

Output:

apple
apple
apple

grep scans the file and prints only the matching lines.

Case Insensitive Filter

You can ignore case with -i:

grep -i apple data.txt

This will match all of them.

Filter and Save to Another File

You can also filter and save the result:

grep apple data.txt > apples.txt

Now apples.txt contains only the filtered lines.

Filter Using Pipe

You can combine commands:

cat data.txt | grep apple

The pipe | sends the output of the first command to the second command.

Part 1 can be found here : https://dev.to/leriaetnasta/complete-microservices-architecture-with-spring-boot-spring-cloud-eureka-gateway-and-openfeign-5a2m

lou — Sat, 21 Feb 2026 11:15:02 +0000

Part 2: Complete Microservices Architecture - Fault Tolerance and Security

lou ・ Feb 18

#resilience4j #microservices #springboot #java

Part 1: Create a complete Microservices Architecture with Spring Boot, Spring Cloud, Eureka, Gateway, and OpenFeign

lou ・ Feb 11

#springcloud #springboot #java #microservices

[Boost]

lou — Fri, 20 Feb 2026 11:51:23 +0000

Part 2: Complete Microservices Architecture - Fault Tolerance and Security

lou ・ Feb 18

#resilience4j #microservices #springboot #java

Part 2: Complete Microservices Architecture - Fault Tolerance and Security

lou — Wed, 18 Feb 2026 19:36:42 +0000

Fault Tolerance with Resilience4j

Security with Keycloak, OAuth2, and OpenID Connect

Fault Tolerance in Microservices

In a distributed system, issues can happen at any time. Instead of showing errors to the client, we should return a result, either from cache or default values, based on the app logic. This is exactly where fault tolerance patterns become important.

For that reason, we will be using resilience4j. This is a dependency that is widely used in distributed architecture to manage fault tolerance problems.

It provides several resilience design patterns:

Circuit Breaker
Retry
Rate Limiter
Time Limiter
Bulkhead
Cache

More on this here:
https://resilience4j.readme.io/docs/getting-started

Circuit Breaker Design Pattern

In this pattern, when service A calls service B and everything is working correctly, the circuit remains closed, and the communication happens normally without interruption.

However, when a problem occurs, the circuit breaker intervenes to manage this communication. It acts as a proxy between service A and service B, controlling the calls and applying the rules defined by the design pattern to handle the failure properly.

Rate Limiter Pattern

When we create APIs but we want to limit access to the API, we can give access to the client using an API key. However, we don't want requests to surpass a certain number of calls per day, per hour, per week, etc. This helps us respect the capacity of our system.

Time Limiter Design Pattern

When we want to call a service, this service that is remote can take time. So we configure a timeout. Once we send the request, we wait for a defined duration, and if the time limit is surpassed, we stop waiting and use an alternative option (fallback).

Retry Design Pattern

It is a mechanism where, when a service calls another service and there is an issue, it waits for a defined duration and then tries again. This process can be configured with a number of attempts and a waiting time before we finally consider it a real failure.

Bulkhead Pattern

This pattern is used to control concurrent requests. If we don't want the number of simultaneous calls to surpass a certain limit, we configure a maximum number of concurrent requests to protect the system from overload.

Cache pattern

resilience4j also offers a cache. when the cache is used in a method, the result is saved there. with it, we can easily return cached data, and it can also work together with the circuit breaker.

where do we find the result whenlets start with circuit breaker:
the idea is that when service A wants to call service B, in the absence of a circuit breaker, if there is an issue, an exception is returned. if we do nothing, what happens is that in the app we have to manage the exception within the app, for example by showing an error to the user.

the solution is to use a circuit breaker. it is a proxy: when we want to call service B, the call is done through the circuit breaker. then the circuit breaker will try the call first, and when we have a response without error, we pass it normally. but if there is an issue, an exception happens, and in that case the circuit breaker manages the state.

it starts in closed state (no issue). when failures reach a threshold, it goes to open state. and when it is open, whenever we ask it to get a result from the service, it will return a fallback result (for example from cache) to return a response while it stays open. during that time, and while the duration is not surpassed, it does not call the service.

once the waiting duration is surpassed, it tries calling the service again. if it fails again, it repeats the same steps and stays open again. but once it tries after the duration ended and the service works, it goes to half-open state. this is where it starts calling the service sometimes to see if there are still issues in the requests. if the failures surpass the threshold, it goes back to open. otherwise, if the requests work without errors and stay below the threshold, it goes back to closed state.

so globally it manages 3 states: closed, open, half-open.

In your project you will have to add a dependency:

spring cloud starter circuitbreaker resilience4j

and you will also need to add the annotation to configure the circuit breaker.

so in our billing service, if we want a bill, the service will need to call the customer service via open feign, which sends the request to the customer service and retrieves the customer data.

now to manage this communication via a circuit breaker, we have to add a method to call a distant service, using the annotation @CircuitBreaker and it expects the following config: the name, and fallbackMethod. this method will call the service, and when there is a failure, it won't return the exception to the user, it will call the fallback method instead.

and the fallback method will accept the path variable and the exception.

let's see this with an example:

the exception is an obligatory field:

when the circuit breaker calls the method, it catches the exception. and when it calls the fallback method, it sends the parameters and the exception, so that we know what kind of error happened or any extra data from the exception.

dummy example :

the essential thing is: when we retry, if there is an error, it retries, and when the number of retries is surpassed, it calls this local method (fallback) that will return the method result.

Configuration

you will need actuator, which we saw in part 1. you will also need to activate the circuit breaker.

if you want to register the circuit breaker in actuator using the health endpoint, and you want /health to return the circuit breaker details, then show-details should be always.

for circuit breaker configuration: there are default values, but we can personalize them. to do that, we configure it like this (where customerService is the name of the circuit breaker):

resilience4j.circuitbreaker.isntances.customerservice.regiter-health-indicator=true

this means: we want to register the health state of this circuit breaker in actuator, so that when you use /health you will see the circuit breaker state.

we also have other params like the event consumer buffer size: it uses a buffer in memory to store a number of calls, and based on that it decides whether to move to open, closed, or half-open.

when would it go from closed to open? we use a threshold:

resilience4j.circuitbreaker.isntances.customerservice.failure-rate-threashold=20

when 20% of the requests fail, then we move to open state.

the minimum number of calls:

resilience4j.circuitbreaker.isntances.customerservice.minimum-number-of-calls= 10

it waits for 10 requests before changing states.

resilience4j.circuitbreaker.instances.customerService.automatic-transition-from-open-to-half-open-enabled=true

this means that going from open to half-open, after surpassing the timeout, it transitions automatically to half-open.

resilience4j.circuitbreaker.instances.customerService.wait-duration-in-open-state=5s

it waits in open state for 5 seconds before going to half-open.

resilience4j.circuitbreaker.instances.customerService.permitted-number-of-calls-in-half-open-state=5

when we are in half-open state, this is how many calls we allow.

resilience4j.circuitbreaker.instances.customerService.sliding-window-size=10

this says that we have a window of 10 requests.

resilience4j.circuitbreaker.instances.customerService.sliding-window-type=count_based

this means that state decisions are based on the number of requests (count-based). there are other types, like time-based.
and for retry configuration:

resilience4j.retry.instances.retrySearchCustomers.max-attempts=15

how many retries we can make.

resilience4j.retry.instances.retrySearchCustomers.wait-duration=5s

how many seconds we wait before retrying again.

let's get hands on:
reminder: what we want as a client is to send a request to the gateway to get the first bill. the gateway will retrieve the address of the billing service from the discovery service. once it gets it, it calls the billing service to get the bill. the billing service will then call the customer service to get the data for that client, and the inventory service to get the product data, before generating the response and sending it back to the client.

if the customer service isn't working, how would we get the customer's data? this is where the circuit breaker should come in handy.

when the service fails and there is an error, we don't want to just display an error. we want to instead retrieve the data, for example from some cache, or return default values depending on the app logic.

start the microservices in this order:

discovery service (eureka service)
config service
customer service
inventory service
billing service
spring cloud gateway

go to your billing service pom.xml and add the following dependencies:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>

once you reload the maven project, you will get access to the circuit breaker annotation. in your feign project, target the customer rest client and let's add the configuration like this:

now onto configuring the circuit breaker. this should be done at the config repo level, but for demonstration purposes we will use the billing service application.properties.


management.health.circuitbreakers.enabled=true
management.endpoint.health.show-details=always
resilience4j.circuitbreaker.instances.customerServiceCB.register-health-indicator=true
resilience4j.circuitbreaker.instances.customerServiceCB.event-consumer-buffer-size=15
resilience4j.circuitbreaker.instances.customerServiceCB.failure-rate-threshold=20
resilience4j.circuitbreaker.instances.customerServiceCB.minimum-number-of-calls=5
resilience4j.circuitbreaker.instances.customerServiceCB.automatic-transition-from-open-to-half-open-enabled=true
resilience4j.circuitbreaker.instances.customerServiceCB.wait-duration-in-open-state=5s
resilience4j.circuitbreaker.instances.customerServiceCB.permitted-number-of-calls-in-half-open-state=5
resilience4j.circuitbreaker.instances.customerServiceCB.sliding-window-size=10
resilience4j.circuitbreaker.instances.customerServiceCB.sliding-window-type=count_based

To know the state of your services and the circuit breaker, you can check the state of your CB here: http://localhost:8888/billing-service/actuator/health

as we can see, the status of the circuit breaker is still CLOSED because the service is working.

"circuitBreakers": {
      "status": "UP",
      "details": {
        "customerServiceCB": {
          "status": "UP",
          "details": {
            "failureRate": "-1.0%",
            "failureRateThreshold": "50.0%",
            "slowCallRate": "-1.0%",
            "slowCallRateThreshold": "100.0%",
            "bufferedCalls": 1,
            "slowCalls": 0,
            "slowFailedCalls": 0,
            "failedCalls": 0,
            "notPermittedCalls": 0,
            "state": "CLOSED"
          }
        }
      }

this time, we will stop the customer service, to explicitly create a fault and be able to test our circuit breaker.
launch: http://localhost:8888/billing-service/actuator/health

now launch: http://localhost:8888/billing-service/api/bills and keep refreshing until you reach the threshold. then recheck the actuator health: you will see that the state of customerServiceCB has changed to half-open ("state": "HALF_OPEN").

"circuitBreakers": {
      "status": "UNKNOWN",
      "details": {
        "customerServiceCB": {
          "status": "CIRCUIT_HALF_OPEN",
          "details": {
            "failureRate": "-1.0%",
            "failureRateThreshold": "50.0%",
            "slowCallRate": "-1.0%",
            "slowCallRateThreshold": "100.0%",
            "bufferedCalls": 3,
            "slowCalls": 0,
            "slowFailedCalls": 0,
            "failedCalls": 2,
            "notPermittedCalls": 0,
            "state": "HALF_OPEN"
          }
        }
      }

and that means that we're now returning the default data. we could also retrieve data from the cache by adding the annotation @Cacheable, which will start caching your data when you consult it from your service, so that when the service is down you can retrieve the cached result. but in our case, since it's a different design choice, we will keep using our default values.

now let's start the customer service and then restart the billing service. after that, launch the actuator /health again, it should have gone back to CLOSED state:

"circuitBreakers": {
      "status": "UP",
      "details": {
        "customerServiceCB": {
          "status": "UP",
          "details": {
            "failureRate": "-1.0%",
            "failureRateThreshold": "50.0%",
            "slowCallRate": "-1.0%",
            "slowCallRateThreshold": "100.0%",
            "bufferedCalls": 19,
            "slowCalls": 0,
            "slowFailedCalls": 0,
            "failedCalls": 0,
            "notPermittedCalls": 0,
            "state": "CLOSED"
          }
        }
      }

more on resilience4j: https://resilience4j.readme.io/docs/circuitbreaker

Security:

When you have a microservices architecture, you need to follow best practices for securing distributed services. Generally, we need an authentication and authorization system, such as OAuth2 and OpenID Connect, which use JWT. Keycloak is one of the most widely used tools based on OAuth2 and OpenID Connect.

A user from the UI goes through a gateway. We call an authentication service, retrieve the username and password, and the service verifies the data. It then generates a JWT, which is returned to the web or mobile application. Every time we send a request to a service, we include the JWT, which represents the user session. The JWT is sent to the microservice, which verifies the token signature to retrieve the user session. Based on that, we determine whether the user has the right to access the requested data or not.

To create an authentication system, we have two approaches: stateful and stateless authentication. In the first solution, the session data is saved on the server. In the second solution, the session data is stored inside a token, which is delivered to the client. The session is contained within that token and is sent with every request.

Stateful:

User sends login data, the service looks for his identity in the database and retrieves his data and role. Then we verify if the password is correct, and we save the session in memory, including his username and role, to know what actions he is allowed to perform.

Once the session is created, it has a session ID, usually a unique UUID. Since the session is stored on the server, we send the session ID to the client in the HTTP response, and it is saved as a cookie. So in a stateful solution, the session is stored on the server, and the user stores the session ID on the client side.

Whenever the user sends a request from his machine, the browser automatically sends the cookies, including the session ID. The server then looks at the list of sessions, checks if the session is still open, and based on that identifies the user and his role. To determine authorization, if the user has the right to perform the action, we respond with status code 200; otherwise, we return 403.

Stateful authentication is very practical for server-rendered HTML applications; it is practical and secure. However, when the backend and frontend are separated, it is not very practical. This is where we use stateless authentication.

Stateless:

User gives username and password, we go to the database to retrieve the user's data, and if the password is correct, we generate a token. It is a chain of characters where we store the user session. One of the most popular tokens is JWT (JSON Web Token). It is in JSON format and contains a lot of information such as the expiration date, role, and username, these are called claims.

We then generate a hash, called a digital signature, which guarantees that this token cannot be modified. If someone tries to change the token, we will detect it using this signature.

Once the token is generated, we deliver it to the client in the response. The client application is responsible for storing the token, which contains the user session, for example in session storage.

Now I am authenticated, and the server does not have to save anything. That is why it is called stateless, meaning no server-side memory. You ask me to authenticate, I authenticate, you give me the session (in the form of a token), and I store it. The server does not remember anything and does not store the session at its level.

Each time the client sends a request, it must include an Authorization header containing the token. When the server receives the token, it verifies the signature. It must know the key (public or private, depending on the algorithm) to verify the signature. If the signature is correct, we retrieve the user session from the token. Based on the role inside the token, we determine whether the user has the right to perform the operation. Otherwise, the response is 403.

In application security, we distinguish between stateful and stateless authentication. Stateless authentication is widely used in distributed systems.

The JWT:

JWT is very popular and largely used. it is a standard that defines a compact and autonomous token that doesn't require any third party to consult the stored data. it has 3 parts: header, payload, signature.

the header contains the algorithm used to calculate the signature. for example RSA uses a private and public key: the private key is used to sign, and the public key is used to verify.
the payload is a JSON object that contains a group of claims.

standard (registered) claims:

subject: username
issuer: app address that generated the token
audience: the public client
issued at: when the token was generated
expiration: when the token will expire
not before: when the token becomes valid

private claims: you can add whatever other data you want, depends on the app needs.
so the user session here is the payload

private claims: you can add whatever other data you want, depending on the app needs. so the user session here is the payload.

the signature is calculated through the algorithm: we take the header

payload and give it to the algorithm with the private key to generate the hash. the signature depends on the header and payload, so if anything changes, the signature won't match.

so JWT is: header.payload.signature. when the user sends the JWT to the microservice, it has to verify the signature.

example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

we retrieve the header eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 to know the algorithm. then, assuming we have the public key, we use the algorithm with the header + payload to calculate the signature. to know if the data hasn't been tampered with, we compare the signature we generated with the signature we received in the JWT.

for more details: https://www.jwt.io/introduction#why-use-json-web-tokens

vulnerability types: CSRF

this type of vulnerability forces a user who is authenticated in an app to perform an operation without realizing it. how?

let's say our client wants to access his bills. he signs in using his credentials, the app retrieves his username and password from the database and compares them with the stored data. if they match, it creates a session. the session is now open and has a session ID. this session ID is sent in the HTTP response and stored in cookies. the issue here is the cookies.

let's say you're authenticated, and a third party manages to use your cookies. they send you a URL disguised as a coupon email, for example. if you click on it, the URL sends a request to the bank server to transfer money from your account to someone else's account.

the server verifies if the session is open. since the cookies are automatically sent with the request, the server finds the session ID, checks that you are authenticated and have the right to perform the operation, and then executes the request, even though you did not intentionally make it.

more details: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF

so how do we mitigate against this in a stateful solution?

whenever the client requests a page from the server, the server should generate a CSRF token. it stores this token in the session and also sends it inside the form as a hidden field. this hidden field contains the CSRF token and ensures that the page comes from the same server.

let's say you submit a form. how do we know it's not a CSRF attack? when the request is received, the server reads the hidden field, retrieves the CSRF token from the form, and compares it with the one stored in the session. if they match, we know the request comes from the same legitimate page. that's why when you work with spring boot, it automatically adds this CSRF field.

but when we use a stateless solution, we don't use this mechanism because we don't rely on cookies. this vulnerability mainly happens because of cookies in stateful authentication.

a session also has a timeout. even if your session is still open, if a malicious app on your machine tries to send a request to the server using your cookies, it will be using your active session. the server will not detect it as malicious because it only checks the session ID.

*reminder about cross-origin resource sharing (CORS) *

when the browser sends a request to a frontend server, you are requesting a page. from that page, if you want to send a request (for example using the POST method) to another domain, the browser does not allow it directly if the domain is different.

before sending the actual request, the browser sends a preflight request using the HTTP method OPTIONS to ask the server which types of communication are allowed.

the server responds with headers such as:

Access-Control-Allow-Origin: if this header is *, it means requests from any domain are allowed. otherwise, if the domain is not allowed, the browser will show a CORS error.
Access-Control-Allow-Headers: this lists which headers are allowed in the request.

so the server must explicitly allow the origin and headers. if you set *, all kinds of headers and domains are allowed.

OAuth2:

open-authorization protocol: it is made to delegate authorization to a third party, so you could use Google, for example, to get authenticated. if you choose Google, it will open a new window to allow you to sign in, and afterwards you're redirected back to the app.

you have the client app that is trying to access the backend, which is a protected resource requiring authentication. instead of the backend handling authentication directly, it redirects you to the authorization server and sends some parameters to identify which client made the request. you need to create a client ID, and the callback URL will contain the URL of your server so that after authentication it can redirect back to it.

what does the authorization server do? it shows a login form that you fill in with your credentials. once submitted, the authorization server authenticates you. we use OpenID Connect for this, which means authentication can be done by a third party that manages user data.

after successful authentication, the authorization server generates an authorization code, which expires quickly (usually in a few seconds). this code is sent to the resource server, which contains the protected resource. the resource server receives the authorization code and verifies that it is valid and not expired by contacting the authorization server. if it is valid, the resource server retrieves the token (in the case of OpenID Connect, this is usually a JWT), which contains the user session. then the resource server opens the session and grants access to the resource.

so authentication is handled through the authorization server, and once the user is authenticated, they are redirected back to the app and given access to the resource. that is the basic principle.

OpenID Connect

this uses the ID token and includes two main tokens: the access token and the refresh token. what are they?

to understand this, what is the issue with JWT? when we generate a JWT, we must add an expiration date. let's say we give it a validity of one year. this means the user will have access for one year. if we want to revoke that access, we would have to wait until the token expires, which is not practical.

that's why OpenID Connect uses two tokens:

the access token, which has a short lifetime and is used to access protected resources.
the refresh token, which has a longer lifetime and is used to generate new access tokens.

when accessing a resource, the client uses the access token, and the application reads the user role and permissions from it. when the access token expires, the refresh token is used to request a new access token. however, once the refresh token expires, the user must authenticate again.

so what is the advantage? even though the refresh token has a longer lifetime, each time a new access token is requested, the system can re-check the user's roles and permissions. this allows the system to verify whether the user is still authorized to access the environment before issuing a new access token.

Keycloak:

is an open source technology developed with Java that lets us do 3 things:

identity management
authentication using OpenID Connect
delegation of authorization using the OAuth2 protocol

once you start it, it uses an H2 database by default. later we can replace it with a different database like PostgreSQL, but for development purposes we can keep H2.

you have a frontend and a backend app, and to protect them we use Keycloak adapters. for the backend, we use Spring Security, which lets us secure the backend. for the frontend, we use Keycloak adapters, which are libraries that make securing the app easier.

when you try to access the frontend without being authenticated, it redirects you to Keycloak, which shows an authentication window. after you provide your credentials, it performs the authentication and generates an authorization code. you are then redirected back to your frontend, which communicates with the backend. the backend requires a token, retrieves the JWT, and opens the session.

when the browser requests a resource from the backend, the frontend sends the JWT to the backend. once the backend receives the JWT, it verifies the signature, which requires the public key. we retrieve this public key from Keycloak. after that, everything follows the same principle as explained before.

so we need to install Keycloak.
pay attention to always install the latest version, because updates usually include security fixes.

how to install Keycloak:
https://www.keycloak.org/getting-started/getting-started-zip

how to start it:
https://www.keycloak.org/getting-started/getting-started-zip#_start_keycloak

after starting it, launch:
http://localhost:8080/
to access the following administration console:

the first step is to navigate to manage realms and create a realm through the UI. we need it to store our application clients so we can assign roles and control authorization. if you have an LDAP directory (annuaire LDAP), you can configure it instead of managing identities directly inside realms.

once it is created, create a new client:

keep the default options (this is just a demo client), then save and click on create a role:

then create a new user:

create a password:

then click on role mapping, choose assign role, select client role, pick the admin role we previously created, then click assign:

now go to your realm settings and click on the OpenID Connect endpoint configuration:

or simply launch:

http://localhost:8080/realms/{your realm name}/.well-known/openid-configuration

you will get a JSON response. retrieve the token endpoint (token_endpoint) and call it from your API client (I am using HTTPie).

it will generate both:

the access token, which expires in 5 minutes ("expires_in": 300)
the refresh token, which expires in 30 minutes ("refresh_expires_in": 1800)

the refresh token is only used to renew access tokens.
if you want to authenticate using the refresh token, your request body will look like this:

now that we saw how to authenticate with a refresh token, let's look at how to authenticate using a client secret:

now we will use the client secret, which we retrieve from the client credentials section:

Part 1: Create a complete Microservices Architecture with Spring Boot, Spring Cloud, Eureka, Gateway, and OpenFeign

lou — Wed, 11 Feb 2026 18:00:39 +0000

Reminder of Microservices Request Flow:

All HTTP requests go through the Gateway.
From the URL path, the Gateway determines the target microservice name.
The Gateway queries the Registration (Discovery) Service using this name, which returns a list of healthy service instances.
The Gateway performs load balancing by selecting one healthy instance.
The Gateway forwards the request to the selected microservice.
The microservice returns a response to the Gateway, which then returns the response to the client.

Let's create our app:

Create a maven parent project with Java 25.
This project will contain all microservices as modules.

Customer service

We start by creating the Customer Service, which will be responsible for managing customer data.
Using Spring Initializr, generate a new Spring Boot module and include the following dependencies:

Spring web
Lombok
Spring data JPA
Spring data REST (rest repositories)
H2 database
Spring Cloud config client
Spring Boot Actuator
Eureka Discovery client

Models:

We will use JPA to map our Java classes to database tables.
For example, the Customer entity can be defined as follows:

package net.lou.customerservice.entities;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import lombok.*;

@Entity
@NoArgsConstructor @AllArgsConstructor @Getter @Setter @Builder
public class Customer {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;
}

JPA Annotations Explained:

@entity
Marks the class as a JPA entity and maps it to a database table.

@id
Indicates the primary key of the entity. Every JPA entity must define exactly one identifier.

@GeneratedValue
Specifies how the primary key is generated.
Using GenerationType.IDENTITY delegates ID generation to the database, which automatically increments the value for each new record.

Lombok Annotations:

Lombok is used to reduce boilerplate code.

@NoArgsConstructor and @AllArgsConstructor generate constructors.

@Getter and @setter generate accessor methods.

@builder enables the builder pattern, making object creation more readable and flexible.

Example usage with the builder pattern:

 @Bean
    CommandLineRunner commandLineRunner(CustomerRepository customerRepository){
        return args ->{
            customerRepository.save(Customer.builder().firstName("lou").lastName("test").email("test@email.com").build());
        };

    }

This allows us to preload the database with sample data when the application starts.

Service Configuration:

The Customer Service is designed to integrate with both:

Discovery Service (Eureka)
Configuration Service (Spring Cloud Config)

To enable service discovery, add the following property

spring.cloud.discovery.enabled=true

For now, this will be set to false until the Discovery Service is implemented.

Similarly, to enable the connection to the configuration server:

spring.cloud.config.enabled=true

This allows the Customer Service to retrieve its configuration from the Config Server once it is available. We will set it to false.

Inventory Service

To create our Inventory Service, we will follow the same steps above.
Our Product entity will be defined as follows:

@Entity
@NoArgsConstructor @AllArgsConstructor @Getter @Setter @Builder @ToString
public class Product {
    @Id
    private String id;
    private String name;
    private double price;
    private int quantity;
}

Gateway Service

To route client requests to our microservices, we introduce an API Gateway.
This gateway will act as a single entry point, handling request routing, filtering, and cross-cutting concerns.

Create a new module named gateway-service using Spring Initializr, and add the following dependencies:

Gateway
Spring Cloud Actuator
Config Client
Eureka Discovery Client

Static Routing Configuration:

In the gateway, routes can be defined using a YAML configuration file.
Each route specifies:

URI (target service),
predicates (conditions to match incoming requests),
filters (Used to modify requests and responses, for example: add, remove, or modify request headers)

Example configuration:

spring:
  cloud:
    gateway:
      routes:
        - id: example-route
          uri: http://example-service
          predicates:
            - Method=GET
            - Path=/api/example/**
          filters:
            - YourCustomFilter

This approach assumes that the service URI is known ahead of time.
However, in a real microservices architecture, services are dynamic: instances can start, stop, or change addresses.

In practice, we only know the microservice name, not its physical location.

Discovery Service

To solve this problem, we introduce a Discovery Service.
Its role is to:

allow microservices to register themselves,
enable the Gateway to discover services dynamically by name,
decouple service consumers from hardcoded URIs.

Create a new module named discovery-service and add a single dependency:

Enabling the Eureka Server

In the DiscoveryServiceApplication class, enable Eureka using:

@EnableEurekaServer

Discovery Service Configuration:

Add the following properties to the Discovery Service configuration to:
1.Prevent the server from registering itself as a client.
2.Prevent it from fetching its own registry.
3.Define the Eureka server address.


spring.application.name=gateway-service
server.port=8888
spring.cloud.config.enabled=false
spring.cloud.discovery.enabled=true
eureka.client.service-url.defaultZone=http://localhost:8761/eureka
eureka.instance.prefer-ip-address=true
spring.cloud.gateway.discovery.locator.lower-case-service-id=true

Once the service is running, you should be able to access the Eureka dashboard at:

http://localhost:8761

You will see a web interface listing all registered microservices:

This was the static way. Let’s now configure it the dynamic way.
In the GatewayServiceApplication, create a bean named locator that returns an object of type DiscoveryClientRouteDefinitionLocator:


  @Bean
    DiscoveryClientRouteDefinitionLocator locator(
            ReactiveDiscoveryClient rdc, DiscoveryLocatorProperties dlp){
        return new DiscoveryClientRouteDefinitionLocator(rdc,dlp);
    }

If you run the service and launch

http://localhost:8888/product-service/api/products,

this should return the product list.

Billing Service

Now that we have our Product and Customer services, we can create the Billing Service that connects them.

Before creating the module, let’s clarify the relationships:

A Customer can have multiple Bills.
Each Bill belongs to one Customer.
A Bill can contain one or more Product items.
Each Product item references exactly one Product.
The same Product can appear in multiple Product items across different Bills.

Create your billing-service module and add the following dependencies:

Spring Web
Spring Data JPA
H2 Database
Eureka Discovery Client
Lombok
Rest Repositories
Config Client
OpenFeign
Spring HATEOAS

Create 2 Repositories, entities and model.
In your entity repository create 2 Classes:

Bill:

@Entity
@NoArgsConstructor @AllArgsConstructor @Getter @Setter @Builder
public class Bill {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private Date billingDate;
    private long customerId;
    @OneToMany(mappedBy = "bill")
    private List<ProductItem> productItems = new ArrayList<>();
}

ProductItem:

@Entity
@Getter @Setter @NoArgsConstructor @AllArgsConstructor @Builder
public class ProductItem {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String productId;
    @ManyToOne
    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
    private Bill bill;
    private int quantity;
    private double unitPrice;
}

In your model repository, create DTO classes for the Customer and Product:

@Getter @Setter
public class Customer {
    private Long id;
    private String name;
    private String email;
}

@Getter @Setter
public class Product {
    private String id;
    private String name;
    private double price;
    private int quantity;
}

To manage the entities, create JpaRepository interfaces for the two entities Bill and ProductItem:

public interface BillRepository  extends JpaRepository<Bill, Long> {
}

public interface ProductItemRepository extends JpaRepository<ProductItem, Long> {
}

To manage customers and products across microservices, we use OpenFeign.

And in your Bill class, add a field called customer of type Customer. The annotation @Transient will serve as an indicator that the field does not exist in the database:

@Transient private Customer customer;

Then go to your ProductItem class and add the following field:

@Transient private Product product;

Create a repository for Feign clients, and add interfaces for customer-service and inventory-service:

@FeignClient(name = "customer-service")
public interface CustomerRestClient {
    @GetMapping("/api/customers/{id}")
    Customer getCustomerById(@PathVariable Long id);

    @GetMapping("/api/customers")
    PagedModel<Customer> getAllCustomers();

}

@FeignClient(name = "inventory-service")
public interface ProductRestClient {
    @GetMapping("/api/products/{id}")
    Product getProductById(@PathVariable String id);
    @GetMapping("/api/products")
    PagedModel<Product> getAllProducts();
}

For example, calling getCustomerById(@PathVariable Long id) sends an HTTP request to the customer-service.
The Discovery Service resolves the microservice’s address. The request is sent to /api/customers/{id} (the id comes from the @PathVariable).
The Customer Service returns a JSON with the Customer data, which OpenFeign maps to the Customer object.

To sum it up: To look up data from your database, you use Spring Data JPA. To retrieve data from another microservice, you use OpenFeign.

Configuration Service (Spring Cloud Config)

The Configuration Service allows microservices to externalize their configuration instead of hardcoding it inside each service.
This makes configuration centralized, consistent, and easy to change without rebuilding services.

Each microservice retrieves its configuration at startup from the Config Server using its application name.

Enabling Config Client in a Microservice

To enable configuration retrieval from the Config Server, add the following dependency:

Spring Cloud Config Client

This allows the microservice to fetch its configuration remotely at startup.

Microservice Configuration:

In the microservice application.properties make sure the spring cloud config is enabled and specify the config server address:

spring.cloud.config.enabled=true
spring.config.import=optional:configserver:http://localhost:9999

** Testing Configuration Retrieval:**

To verify that the configuration service is working, create a REST controller and inject configuration values using @Value annotation

Example configuration stored in the Config Server:

config.params.param1=80
config.params.param2=20

Injecting the values:

@Value("${config.params.param1}")
private String param1;

@Value("${config.params.param2}")
private String param2;

Expose an endpoint to test:

@GetMapping("/testConfig1")
public Map<String, String> configTest() {
    return Map.of("param1", param1);
}

Calling this endpoint confirms whether the configuration was successfully loaded from the Config Server

Option 2:

For structured and scalable configuration, it is better to group related properties into a configuration class.

Example configuration class:

@ConfigurationProperties(prefix = "config.params")
public record CustomerConfigParams(String param1, String param2) {}

The prefix config.params automatically maps:

config.params.param1 → param1
config.params.param2 → param2

Enabling Configuration Binding:

In the main application class, enable configuration properties:

@EnableConfigurationProperties(CustomerConfigParams.class)
@SpringBootApplication
public class CustomerServiceApplication {
}

This tells Spring to create a bean of CustomerConfigParams and make it injectable.

Injecting and Exposing Configuration:

Inject the configuration bean into a REST controller:

@Autowired
private CustomerConfigParams customerConfigParams;

Expose it through an endpoint:

@GetMapping("/testConfig2")
public CustomerConfigParams configTest2() {
    return customerConfigParams;
}

This endpoint returns all configuration values bound from the Config Server:

Each time we update the config, we need to restart the microservice.

Refreshing Configuration at Runtime:

To ensure that configuration values stay up to date without restarting the microservice, Spring Cloud provides a refresh mechanism.

In your REST controller, add the annotation@RefreshScope This tells Spring that the bean should be recreated when a configuration refresh is triggered.

When a refresh occurs, Spring:

Reinstantiates the controller
Re-injects configuration values (@Value and @ConfigurationProperties)
Applies the updated configuration at runtime

Example:

@RestController
@RefreshScope
public class ConfigTestRestController {
}

Building and Starting the Microservices:

Once all modules are implemented, start the services in the following order:

Configuration Service
Discovery Service
Customer Service
Inventory Service
Billing Service
Gateway Service

This order ensures that:

The Configuration Service is available before other services attempt to load their external configuration.
The Discovery Service is running before microservices try to register themselves.
The Gateway Service starts after all backend services are registered and discoverable.

Testing the API:
Once all services are running successfully, you can test the system through the Gateway Service, which acts as the single entry point for all client requests.

Source Code

You can find the complete project source code here:
https://github.com/leriaetnasta/my-mini-souq-micro-services

A Step by Step Guide to Building Lightning Fast APIs

lou — Fri, 14 Feb 2025 15:27:53 +0000

FastAPI is a Python framework that lets you build APIs with speed and simplicity. It supports async programming and that's what makes it fast.
In this guide, I’ll walk you through creating your first FastAPI project, enhancing it with data models, integrating a database, and even securing your endpoints with JWT authentication.

A Dummy FastAPI Project

Let’s kick things off with a basic API:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}


@app.get("/hello/{name}")
async def say_hello(name: str):
    return {"message": f"Hello {name}"}

You might be wondering, what’s happening here?
We Created:

An instance of the class FastApi from the module fastapi.
A variable, app, which will serve as the point of interaction to create the api.
Used decorator, @app followed by the HTTP method, get, put, post, delete
Passed the endpoint to the decorator and defined the operation function

Try it out by running your server and visiting

http://127.0.0.1:8000/docs

To explore the interactive documentation

Your First FastAPI Project

Now let's create a model to hold the schema of our data type. There's one problem with using plain Python classes for this: FastAPI won't know how to handle these models automatically, meaning you'll have to manually parse and validate the request body. To avoid this, use Pydantic's BaseModel as recommended in their documentation.

Let's explore how to add a Starship to our API by defining its data type using a Pydantic model:

First, we import BaseModel from Pydantic.
Then, we define the Starship class by inheriting from BaseModel and listing out the attributes.
This method automates data validation, making the API easy to maintain.

We’ll dive into the endpoint creation details as we move along. For now launch the following URL to test things out:

http://127.0.0.1:8000/docs#

This interactive docs page lets you see your endpoints in action. All you have to do is simply add the required details and watch the results:

Now, let’s spice things up by adding a Jedi to link each Starship to its purchaser. First, we need to define the fields. Pydantic’s Field is a lifesaver here, it not only lets you add extra information to a field but can also use a default_factory to auto-generate values. This is perfect for automatically creating an ID whenever a new Starship or Jedi is instantiated.

Additionally, you can use Field to make your API documentation richer by adding descriptions. For more details on the available parameters, check out the Pydantic documentation

Note the use of ellipsis within Field. It emphasize on the fact that a value must be provided.

Schema Definition

Since the ID is auto generated, having a well defined schema helps prevent unnecessary inputs from the client. In Pydantic v2, you should now define the JSON schema using model_config = ConfigDict() instead of the deprecated json_schema_extra.

For fields that are computed from other fields, simply add the @computed_field decorator to the property function. It’s recommended to explicitly use the @property decorator, but it isn’t required.

Now let's explore some more Pydantic types, and add them to our code.

HttpUrl is a type that accepts http or https URLs.

We will be using it to provide a list of Photos to show all of the angles of the Starship for a 360 view.

We will be using Form for sign in purposes

Let's try it out

Awesome!

Integrating a Database with SQLAlchemy and SQLite

Now that we want to save the data sent by the client, it's time to integrate a database into our app. We'll walk through the steps of using SQLAlchemy—a popular ORM for Python—together with SQLite. We’re keeping it simple: create a new directory (let’s call it starship_db), set up a virtual environment if you haven’t already, activate it, and run the following command to get started.

pip3 install sqlalchemy fastapi pydantic

Let's set up your project files with a few quick terminal commands. This step creates your SQLite database file and organizes your project structure:

touch starship.db
mkdir starship
cd starship
touch main.py database.py models.py schema.py

The models.py will hold your models, each model is a blueprint for a database table.

Here the Starship class serves as a blueprint for a database table. By setting tablename = 'starship' you're instructing SQLAlchemy to create a table in your database named "starship"

Next take your existing Starship model and add it into your schema.py file to define a response model called StarshipResponse. In this model, make sure to include orm_mode=True this tells FastAPI to serialize your SQLAlchemy objects to JSON, ensuring smooth and accurate API responses.

Managing Database Migrations with Alembic

We’ll use Alembic as our go to migration tool to manage changes to our database schema and keep everything running smoothly as our code grows. Alembic makes it much easier to handle schema updates without the headache of manual migrations.

You need to install Alembic and initialize it

pip install alembic
alembic init alembic

This command will create a new directory named alembic in your project and an alembic.ini file. Inside the alembic directory, there will be env.py file and a versions directory for your migration scripts.

Inside of your alembic.ini file, update sqlalchemy.url
then go to alembic/env.py and change this line

target_metadata = None

to your model's metadata, something like this:

from starship.database import Base
target_metadata = Base.metadata

This will link Alembic with your models and allows it to detect any changes in the models when generating migration scripts.

Initialize the migration with:

alembic revision --autogenerate -m "Init"

And apply it with:

alembic upgrade head

Now let's set up our database connection and session, and define a helper function to yield a session instance. This ensures that your database connections are managed properly, cleaning up after each request:

Defining CRUD Operations for Starships

In your main.py, you'll use the get_db() method to obtain a database session, and then define a POST endpoint to create a new Starship. This endpoint takes the input object, instantiates the model, adds the new entry to the database, commits the transaction, and finally returns the created record. This approach is fundamental for populating your database via API requests.

db.add(starship)
db.commit()
db.refresh(starship)

And just as we define a POST method to add data. We need to define a PUT, GET and DELETE methods for the rest of the operations. After all, managing your data means you'll also need to update, retrieve, and remove entries as needed.
For these operations we will use filter() to search for a specific starship in the database.

Now if we try it out:

Defining Relationships: Connecting Starships to Their Pilots

Every starship needs a pilot. Let's create a User model to represent the pilots who navigate these ships and implement the same CRUD operations as we did for Starships.

Now, let's connect the User with their Starship. A pilot can fly more than one starship at different times. They can fly the Falcon one day and the X-Wing the next. This illustrates a one to many relationship between the User and their Starships.

In our code this translates to adding the ForeignKey for User into our Starship and define a relationship to User. In User we will define a relationship with Starship, here back_populates keyword tells SQLAlchemy that there is a relationship on the User side.

Routes with APIRouter

Previously, we used app to define our routes directly. This can become cumbersome as we write more code. Instead, we can group related routes together using APIRouter with tags. In addition to that, with APIRouter, we can avoid repeating the base URL for each route, by defining a prefix.
It's as simple as importing APIRouter and defining tags and prefix:

from fastapi import APIRouter

router = APIRouter(tags=["starships"], prefix='/starship')

After you're done, let's do some clean up of our previous code, we will replace the @app decorators with @router. Since you've defined a prefix (/starship) in our router, a route defined as:

@router.post('/')

will be accessible at '/starship' rather than '/'

Authenticating our pilots

Let's create our Sign In endpoint.

First define the new models:

We now need to define two essential functions for our authentication system:

generate_token: This function copies the provided data, adds an expiration timestamp, and encodes everything into a JWT using our secret key and algorithm.

get_auth_user: This function uses oauth2_scheme to extract the token from the request header, decodes it, and verifies the user's email. It can be used as a dependency to protect other routes.

But before we can do any of this, we need a secret key. To generate a secure random hexadecimal string, run:

openssl rand -hex 32

We'll use this generated string as our SECRET_KEY and HS256 as our algorithm.

Below is the complete code for these functions:

Now onto our Sign In endpoint. What we need to handle is when a user submits their credentials (email and password), the endpoint should be able to:

Query the database to retrieve the user.
Verify the password.

pwd_context.verify()

If both the email and password are correct, generate a JWT token using our generate_token function.
Return the JWT token as an access token along with the token type 'bearer'.

Let's try it out:

Awesome! Now that we are able to generate our JWT tokens, we should be able to use it to secure our endpoints. Let's tackle our previous starship endpoint.
Take this operation for instance:

@router.get('/', response_model=List[StarshipResponse])
def get_starships(db: Session = Depends(get_db), auth_user: User = Depends(get_auth_user)):
    return db.query(models.Starship).all()

The get_starships function includes this line now

 auth_user: User = Depends(get_auth_user) parameter.

This dependency ensures that only authenticated users can access the endpoint. If a request does not have valid authentication credentials, FastAPI automatically returns a 401 Unauthorized response.

If you go to your docs you will notice a lock

And If you try it out and hit execute it will return unauthorized error
{ "detail": "Not authenticated" }
Great, that means that your endpoint is now secured. To successfully access this secured endpoint, you need to provide a valid JWT token in the Authorization header of your request. The header should be formatted as follows:

Authorization: Bearer your_jwt_token

I hope this guide has been comprehensive. If you have any questions or need further clarification, please leave a comment below.