Introduction

In the previous article you gave your site a real shell: a consistent header and footer, a navigation bar, social media icons, a styled home page, and a responsive hamburger menu. The five inner pages still had placeholder content — just a heading and a paragraph.

This is Part 4 of the series. If you missed the earlier articles, you can start from Getting Started with HTML, Mastering the Basics of CSS, or Building a Professional Website Layout with CSS.

This article builds out those pages for real. Following the Part 3 of the html-hero project lesson by lesson, I will show you how to write the About Me, Start Here, and Resources pages, how to build a contact form with HTML form elements, and how to create an interactive photo gallery using CSS Grid and a handful of lines of JavaScript.

You should read this article if:

• you completed Part 3 and want to move beyond layout into real content pages
• you have never built an HTML form and want to understand how <input>, <label>, <textarea>, and <button> work together
• you want to understand CSS Grid and how it differs from Flexbox for image-based layouts
• you want to add your first JavaScript to a web page without reaching for a framework

All the source code is available in the part-3 folder of the html-hero repository. Each lesson has its own subfolder (lesson-20 through lesson-24) so you can compare the result at every step.

A New CSS File: page.css

Part 2 used two CSS files: default.css (shared by every page) and home.css (home page only). Part 3 introduces a third file, page.css, loaded by all inner pages.

The separation is deliberate. The home page has a hero image, feature rows, and a newsletter section — styles that make no sense on an article page. Inner pages share a different set of needs: a centred content container, floating images, styled blockquotes, form fields, and gallery cells.

<link rel="stylesheet" type="text/css" href="assets/css/default.css">
<link rel="stylesheet" type="text/css" href="assets/css/page.css">
<link rel="stylesheet" type="text/css" href="assets/css/brands.css">
<link rel="stylesheet" type="text/css" href="assets/css/fontawesome.css">

The base rules in page.css centre the content area and handle text and image layout:

#page-container {
    max-width: 1080px;
    margin-left: auto;
    margin-right: auto;
    padding: 10px;
    overflow: hidden;
}

p {
    color: #666666;
    text-align: justify;
}

img.img-left {
    float: left;
    padding: 10px 10px 10px 0px;
}

img.img-right {
    float: right;
    padding: 10px 0px 10px 10px;
}

The overflow: hidden on #page-container is a classic float-clearing trick: it forces the container to expand around any floated images inside it, preventing them from overflowing outside the box.

The About Me Page

The About Me page is the simplest of the five — it follows the same article-style structure as any inner page: a heading, paragraphs of text, and images floated left or right to break the visual monotony.

<main class="page-main">
    <div id="page-container">
        <h1>About Me</h1>
        <img class="img-left" src="assets/img/salvatore_d_angelo.jpeg"
             alt="Salvatore D'Angelo" width="150" height="150">
        <p>
            My name is Salvatore D'Angelo and I am a professional software engineer ...
        </p>
    </div>
</main>

The img-left class floats the profile picture to the left so the text wraps around it on wider screens. On mobile (below 480 px) the float is removed and the image sits above the paragraph, which reads more naturally on a narrow screen:

/* Mobile: no float, image sits above text */
img.img-left {
    padding: 10px;
}

/* Tablets and wider: float left */
@media screen and (min-width: 480px) {
    img.img-left {
        float: left;
        padding: 10px 10px 10px 0px;
    }
}

The float property was the original CSS layout mechanism before Flexbox and Grid existed. It is still the right tool when you want text to wrap around an image.

The Start Here Page and <figure>

The Start Here page introduces two semantic HTML elements you have not seen yet: <figure> and <figcaption>.

A <figure> groups an image with its caption as a single semantic unit. Search engines and screen readers understand that the caption belongs to the image — something a plain <img> followed by a <p> does not communicate:

<figure>
    <img class="responsive_img"
         src="assets/img/software-developer2.jpg"
         alt="Software Developer">
    <figcaption>
        Photo from
        <a href="https://clipartstation.com/">clipartstation.com</a>
    </figcaption>
</figure>

The CSS in page.css handles the caption and link styling:

figure {
    margin: 0px;
}

figure figcaption a {
    color: #1D67B2;
}

The margin: 0 overrides the browser default margin on <figure> (some browsers add 40 px of horizontal margin by default), which would otherwise push the figure away from the page edges unexpectedly.

The Resources Page

The Resources page is a curated list of links. It uses <ol> for ordered lists and demonstrates the target="_blank" attribute, which opens links in a new tab:

<a href="https://developer.mozilla.org/en-US/"
   target="_blank" rel="noopener noreferrer">
    MDN Web Docs
</a>

The rel="noopener noreferrer" attribute is not optional when using target="_blank". Without it, the opened page can access the opener’s window object via window.opener — a security vulnerability known as reverse tabnapping. Always pair target="_blank" with rel="noopener noreferrer".

The CSS rule list-style-position: inside keeps the list numbers visually aligned within the content container rather than hanging outside it:

ol {
    list-style-position: inside;
}

The Contacts Page and HTML Forms

A contact form lets visitors send messages directly through the website. HTML provides all the elements needed — no JavaScript required for the structure.

The <form> tag is the container. Its two most important attributes are action (where to send the data) and method (how to send it). In this project action is empty because there is no backend server:

<form onsubmit="return false">

    <label for="name">Name:</label>
    <input type="text" id="name" name="name"
           placeholder="Your name" required>

    <label for="email">Email:</label>
    <input type="email" id="email" name="email"
           placeholder="Your email" required>

    <label for="message">Message:</label>
    <textarea id="message" name="message" rows="8"
              placeholder="Write your message here..."></textarea>

    <button type="submit">Send Message</button>

</form>

The key elements and their roles:

The for attribute on <label> must match the id attribute on the associated field. This pairing is essential for accessibility: screen readers announce the label when the field receives focus, and clicking the label moves focus to the field.

The required attribute activates browser-native validation — the form cannot be submitted if the field is empty, without a single line of JavaScript.

type="email" is a free input validator: the browser rejects values that do not contain an @ sign and a domain. It is not a substitute for server-side validation, but it catches obvious mistakes immediately.

The form elements are styled in page.css to match the overall site look:

form label {
    display: block;
    margin-top: 10px;
    font-weight: bold;
    color: #444444;
}

form input,
form textarea {
    width: 100%;
    padding: 8px;
    border: 1px solid #cccccc;
    border-radius: 4px;
    box-sizing: border-box;
}

form button {
    margin-top: 12px;
    padding: 10px 24px;
    background-color: #1D67B2;
    color: #ffffff;
    border: none;
    border-radius: 4px;
    cursor: pointer;
    font-weight: bold;
}

box-sizing: border-box is important: without it, width: 100% plus padding would make the field wider than its container. With border-box, the padding is included in the declared width, so the field stays within bounds.

The Gallery Page: CSS Grid and JavaScript

The gallery is the most technically interesting page in Part 3. It introduces two things: CSS Grid for the image grid layout, and a small JavaScript file for the lightbox viewer.

CSS Grid for the Image Grid

Flexbox is ideal for one-dimensional layouts — a row of icons, a column of cards. CSS Grid is designed for two dimensions: rows and columns simultaneously. A photo gallery is the perfect use case.

.gallery-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
    gap: 10px;
    margin-top: 20px;
}

The repeat(auto-fill, minmax(150px, 1fr)) value is the key. Breaking it down:

• auto-fill — create as many columns as fit in the available width
• minmax(150px, 1fr) — each column is at least 150 px wide and at most one equal fraction of the available space

The result is a fully responsive grid: on a wide screen you get many columns; on a phone you might get two or three — with zero media queries.

Each cell clips the image to a fixed height:

.gallery-cell img {
    width: 100%;
    height: 150px;
    object-fit: cover;
    cursor: pointer;
    opacity: 0.85;
    transition: opacity 0.2s ease;
}

.gallery-cell img:hover {
    opacity: 1;
}

object-fit: cover scales the image to fill its cell without distortion, cropping the edges if necessary — the same behaviour as background-size: cover for background images.

The JavaScript Lightbox

When a user clicks a thumbnail, a full-screen viewer opens. This requires JavaScript because it involves responding to a user event and changing the DOM.

The script is kept in a separate file, assets/js/gallery.js, and loaded with the defer attribute:

<script type="text/javascript" src="assets/js/gallery.js" defer></script>

The defer attribute tells the browser to download the script in parallel with the HTML, but execute it only after the DOM is fully parsed. This prevents the classic error where a script tries to access an element that has not been created yet.

The gallery HTML uses an onclick attribute to call the JavaScript function:

<div class="gallery-cell">
    <img src="assets/gallery/photo1.jpg"
         alt="Photo 1"
         onclick="showImage(this)">
</div>

The viewer is a hidden <div> that becomes visible when an image is clicked:

<div id="gallery-viewer">
    <span id="gallery-close" onclick="closeImage()">&#215;</span>
    <img id="gallery-expanded-img" src="" alt="">
</div>

The JavaScript is minimal — two functions:

function showImage(img) {
    var viewer = document.getElementById("gallery-viewer");
    var expandedImg = document.getElementById("gallery-expanded-img");
    expandedImg.src = img.src;
    expandedImg.alt = img.alt;
    viewer.style.display = "block";
}

function closeImage() {
    document.getElementById("gallery-viewer").style.display = "none";
}

showImage copies the src and alt from the clicked thumbnail into the expanded image, then makes the viewer visible by setting style.display = "block". closeImage hides it again by setting display = "none".

The viewer is styled as a fixed full-screen overlay:

#gallery-viewer {
    display: none;
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: rgba(0, 0, 0, 0.9);
    z-index: 100;
    text-align: center;
    padding-top: 50px;
    box-sizing: border-box;
}

position: fixed positions the viewer relative to the viewport, not the page — it stays in place even when the user scrolls. z-index: 100 places it above everything else on the page.

The Final File Structure

After all Part 3 lessons, the project has grown from a layout shell to a complete multi-page site:

lesson-24/
├── index.html
├── about-me.html
├── start-here.html
├── resources.html
├── contacts.html
├── gallery.html
└── assets/
    ├── css/
    │   ├── default.css       ← shared by all pages
    │   ├── home.css          ← home page only
    │   ├── page.css          ← inner pages, form, gallery
    │   ├── fontawesome.css   ← Font Awesome core
    │   └── brands.css        ← Font Awesome brand icons
    ├── fontawesome/
    │   └── webfonts/         ← .ttf and .woff2 font files
    ├── img/                  ← site images
    ├── gallery/              ← gallery photos
    └── js/
        └── gallery.js        ← gallery lightbox

The three-CSS-file architecture (default.css, home.css, page.css) keeps each stylesheet focused: shared structure, home-page layout, and inner-page content styles never mix. Adding a new page type in the future means adding a new CSS file, not modifying an existing one.

Conclusion

In this article we covered:

• How to introduce page.css to separate inner-page styles from home-page styles
• How to use floated images on article pages and remove the float on mobile with media queries
• How <figure> and <figcaption> communicate image-caption relationships to browsers and assistive technologies
• How target="_blank" combined with rel="noopener noreferrer" safely opens links in new tabs
• How to build a contact form with <input>, <label>, <textarea>, and <button>, and how browser-native validation works
• How CSS Grid with repeat(auto-fill, minmax(...)) creates a fully responsive photo grid without media queries
• How to write a JavaScript lightbox in two functions and load it with defer

The series has now covered the full beginner path: from a blank HTML file to a complete, responsive, multi-page website with a form and an interactive gallery. This is the final article in the series.

If you enjoyed this article, don’t forget to give it a clap 👏, share it with your friends 🔗, and follow me for more tips and tutorials on software development 📘. Your support helps me create more content like this — thank you! 🙌

Note: English is not my native language, and this article was drafted with the assistance of AI. However, all the ideas, projects, concepts, and content are entirely my own.

Introduction

In the previous articles of this series you built a five-page HTML website from scratch, and in Mastering the Basics of CSS you learned the theory behind stylesheets. You have working pages, but they still look like a plain document from 1999: no header, no navigation bar, no branding, and nothing that adapts to a phone screen.

This article changes that. Following the Part 2 of the html-hero project step by step, I will show you how to turn those raw HTML pages into a visually consistent site with a real layout, social icons, a styled home page, and a responsive mobile menu.

You should read this article if:

• you completed the first HTML article and want to continue building the project
• you know basic CSS properties but have never applied them to a real multi-page layout
• you want to understand how header, footer, navigation bar, and responsive design actually work in practice — not just in theory

All the source code is available in the part-2 folder of the html-hero repository. Each lesson has its own subfolder (lesson-13 through lesson-19) so you can compare the result at every step.

Your First CSS File

Before building the layout, let’s quickly cover what Lesson 11 introduced at the end of Part 1: the first external CSS file.

Up to Lesson 10, all pages were unstyled HTML. Lesson 11 adds a default.css file linked from every page with a single <link> tag in the <head>:

<head>
    <meta charset="UTF-8">
    <title>HTML Hero</title>
    <link rel="stylesheet" type="text/css" href="assets/css/default.css">
</head>

This one stylesheet applies to all pages, which is exactly the right approach for a consistent site. Its base rules set the font, constrain the content width, and add basic typography:

body {
    margin: 0 auto;
    font-family: 'Helvetica Neue';
    font-size: 13px;
}

main {
    max-width: 1080px;
    margin-left: auto;
    margin-right: auto;
}

The max-width on main keeps the content readable on wide monitors while the auto margins keep it centred. This pattern is used throughout the entire project.

Publishing Your Website

Lesson 12 is about going live. The project uses Altervista, a free Italian hosting service, and FileZilla as the FTP client to upload files.

The steps are straightforward: create a free space on Altervista, switch it from the default WordPress plan to a plain hosting plan, then connect FileZilla with the FTP credentials Altervista provides, and upload all your files. This is optional — you can also follow along locally — but it is a useful exercise for understanding how websites actually get published.

Header and Footer with Semantic HTML

Part 2 starts properly here. The first thing every real website needs is a consistent header and footer on every page.

HTML5 introduced the <header> and <footer> tags specifically for these regions. Using them instead of a generic <div> has two benefits: the code is more readable, and search engines and screen readers understand the structure better.

<body>
    <div id="page">
        <header>
            <div id="header-group">
                <div id="logo">
                    <img src="assets/img/code4projects-logo-mini.webp"
                         alt="Code4Projects Logo" width="150" height="150">
                </div>
            </div>
        </header>
        <main>
            <!-- page content here -->
        </main>
        <footer>
            <div id="site-info">
                Code4Projects, Copyright Salvatore D'Angelo &copy; 2016-2025.
            </div>
        </footer>
    </div>
</body>

The CSS gives the header a light background and fixes its height. The #header-group container uses Flexbox to position the logo and, in later lessons, the social icons side by side:

header {
    background-color: #FCFCFC;
    width: 100%;
}

#header-group {
    padding: 0px 35px;
    max-width: 1080px;
    margin-left: auto;
    margin-right: auto;
    display: flex;
    flex-direction: row;
    justify-content: space-between;
}

The key takeaway: semantic tags (<header>, <footer>, <nav>, <main>) are not just cosmetic — they communicate the structure of your page to browsers, search engines, and assistive technologies.

This same header and footer markup is copied to all five HTML files. That repetition is deliberate at this stage: in a real project you would use a template engine or a framework to avoid it, but at the beginner level it is important to understand exactly what is being shared before abstracting it away.

Social Media Icons with Font Awesome

Plain text links for social profiles look dated. The industry standard is to use icon fonts, and Font Awesome is the most widely adopted one.

Font Awesome delivers icons as a web font, which means no image files are needed — each icon is a Unicode character rendered by a font file. The project uses a local copy of Font Awesome to avoid any external dependency. Two CSS files are added to the project:

• assets/css/fontawesome.css — core Font Awesome rules
• assets/css/brands.css — brand icon definitions (Facebook, Twitter, etc.)

These are linked from every page alongside default.css:

<link rel="stylesheet" type="text/css" href="assets/css/default.css">
<link rel="stylesheet" type="text/css" href="assets/css/brands.css">
<link rel="stylesheet" type="text/css" href="assets/css/fontawesome.css">

Adding a social icon button to the header is then a matter of one <a> tag with the right Font Awesome class:

<a aria-label="Code4Projects Facebook page"
   class="social-media-icon social-media-icon-facebook"
   href="https://www.facebook.com/code4projects/">
    <span class="fa-brands fa-facebook-f"></span>
</a>

The social-media-icon class controls the button size and shape (36×36 px, rounded corners). The social-media-icon-facebook class gives it the characteristic blue gradient background. The fa-brands fa-facebook-f classes on the <span> render the actual icon from the font file.

Completing the Footer

With Font Awesome already integrated, completing the footer is straightforward: reuse the same social icon markup inside <footer> and add the copyright text next to it.

<footer>
    <div id="footer-social-media-group">
        <div class="social-media-title">Follow me on:</div>
        <div class="social-media-icons">
            <!-- same icon markup as in the header -->
        </div>
    </div>
    <div id="site-info">
        Code4Projects, Copyright Salvatore D'Angelo &copy; 2016-2025.
    </div>
</footer>

The CSS uses Flexbox to stack the social area above the copyright text and keep everything centred. The important point here is code reuse: once you understand a pattern (icon button with Font Awesome), you apply it in multiple places without reinventing it.

The Navigation Bar

Every multi-page site needs a way to move between pages. A navigation bar is the standard solution, and HTML already has a semantic element for it: <nav>.

The markup uses an unordered list inside <nav>. At this point the links still point to the five original pages by filename:

<div id="navigation">
    <nav>
        <ul>
            <li><a href="index.html">Home</a></li>
            <li><a href="second_page.html">Second Page</a></li>
            <li><a href="third_page.html">Third Page</a></li>
            <li><a href="fourth_page.html">Fourth Page</a></li>
            <li><a href="fifth_page.html">Fifth Page</a></li>
        </ul>
    </nav>
</div>

By default an unordered list is vertical. CSS transforms it into a horizontal blue bar:

#navigation {
    background-color: #1D67B2;
}

nav {
    padding: 5px;
    max-width: 1080px;
    margin-left: auto;
    margin-right: auto;
}

nav ul li {
    padding: 11px 35px;
    display: inline-block;
}

nav ul li a {
    color: #f2f2f2;
    text-decoration: none;
    font-weight: 700;
}

display: inline-block is the key rule: it tells each <li> to sit side by side instead of stacking. The #navigation div gets the blue background, and the link colour is set to near-white so it is readable against that background.

Building the Home Page

Inner pages (the five content pages) all share the same basic structure. The home page is different: it needs a visual impact — a hero image, sections with icons, and featured content. This is why a second CSS file, home.css, is introduced and loaded only by index.html.

The Hero Area

The hero area fills the full width with a background image and overlays a text box on top of it:

.hero-background {
    background-image: url("../../assets/img/code4projects-image-hero.webp");
    background-position: center;
    background-repeat: no-repeat;
    background-size: cover;
    position: relative;
}

.hero-box {
    padding: 50px 40px;
    display: flex;
    flex-direction: row;
    justify-content: flex-end;
}

.hero-messagebox {
    padding: 50px 40px;
    max-width: 400px;
    background-color: RGBA(139, 139, 139, 0.5);
    border-radius: 20px;
}

background-size: cover scales the image to fill the entire element without distortion. justify-content: flex-end pushes the text box to the right side. The semi-transparent grey background (RGBA with 0.5 alpha) makes the text legible over any background image.

The Newsletter Section

A newsletter sign-up section sits below the feature rows. It uses Flexbox to place an eBook cover image and the sign-up form side by side:

<div class="newsletter-home-box">
    <div class="newsletter-home-image">
        <img src="assets/img/3D-DockerCover-medium.png"
             alt="Join our Newsletter and Download a Free eBook">
    </div>
    <div class="newsletter-home-form">
        <div class="newsletter-home-text-title">Download Free eBook</div>
        <form action="#" method="get" target="_blank">
            <input class="newsletter-home-input" name="name"
                   type="text" placeholder="Name" required>
            <input class="newsletter-home-input" name="email"
                   type="email" placeholder="Email" required>
            <button type="submit" class="primary">Download</button>
        </form>
    </div>
</div>

The type="email" attribute on the email field gives you basic format validation for free — the browser will reject submissions that do not look like an email address, without any JavaScript needed.

Making the Site Responsive

A site that works on desktop but breaks on a phone is not a finished site. The final step of Part 2 adds responsive design, which means the layout adapts automatically to the screen size.

The Viewport Meta Tag

The first change is the simplest: add this <meta> tag to the <head> of every page.

<meta name="viewport" content="width=device-width, initial-scale=1">

Without it, mobile browsers scale the page down to fit, rendering it as a shrunken desktop version. With it, the browser uses the actual device width and the layout rules you define via media queries.

Media Queries

The project targets four breakpoints. The diagram below shows how the layout changes at each one:

The project targets four breakpoints:

The CSS follows a mobile-first approach: the default rules are written for mobile, then overridden for wider screens using @media screen and (min-width: ...). For example, the header layout is vertical by default and switches to horizontal row on tablets and above:

/* Default: mobile — vertical stack */
#header-group {
    display: flex;
    flex-direction: column;
    justify-content: center;
}

/* Tablets and wider: horizontal row */
@media screen and (min-width: 480px) {
    #header-group {
        flex-direction: row;
        justify-content: space-between;
    }
}

The Hamburger Menu

On a phone, a horizontal navigation bar does not fit. The solution is a hamburger menu: three horizontal lines that, when tapped, reveal the navigation links in a dropdown.

The implementation uses a hidden checkbox as a CSS-only toggle — no JavaScript required:

<div id="navigation">
    <input class="drop-menu-checkbox" type="checkbox" id="drop-menu-checkbox">
    <label class="hamburger" for="drop-menu-checkbox">
        <span class="hamburger-line"></span>
    </label>
    <nav>
        <ul>
            <li><a href="index.html">Home</a></li>
            <!-- ... -->
        </ul>
    </nav>
</div>

The three hamburger lines are drawn entirely in CSS using ::before and ::after pseudo-elements on .hamburger-line. When the checkbox is checked, a CSS rule makes the <ul> visible:

/* Mobile: nav list hidden by default */
@media screen and (max-width: 479px) {
    nav ul {
        display: none;
    }
}

/* Show nav when checkbox is checked */
.drop-menu-checkbox:checked ~ nav ul {
    display: block;
}

/* Hide hamburger on screens wider than mobile */
@media screen and (min-width: 480px) {
    .hamburger {
        display: none;
    }
}

The ~ is the CSS general sibling combinator: it selects nav ul when .drop-menu-checkbox (the hidden checkbox) is a preceding sibling. Clicking the hamburger label toggles the checkbox, which toggles the menu — no JavaScript at all.

The Final File Structure

After all Part 2 lessons, the project structure looks like this:

lesson-19/
├── index.html
├── second_page.html
├── third_page.html
├── fourth_page.html
├── fifth_page.html
├── favicon.ico
└── assets/
    ├── css/
    │   ├── default.css       ← shared by all pages
    │   ├── home.css          ← home page only
    │   ├── fontawesome.css   ← Font Awesome core
    │   └── brands.css        ← Font Awesome brand icons
    ├── fontawesome/
    │   └── webfonts/         ← .ttf and .woff2 font files
    └── img/                  ← site images

The separation between default.css (shared rules) and home.css (home-page-only rules) is the key architectural decision. It keeps the shared stylesheet focused and makes it clear what is specific to the home page.

Conclusion

In this article we covered:

• How to use <header> and <footer> semantic tags for a consistent page structure
• How to integrate Font Awesome locally to add scalable social media icons
• How to build a horizontal navigation bar from a <ul> with display: inline-block
• How to structure a home page with a CSS background image hero, circular icons, and feature sections
• How to add a newsletter sign-up form with styled <input> fields
• How to apply responsive design with the viewport meta tag, media queries, and a CSS-only hamburger menu

The next article builds out the real content pages: About Me, Start Here, Resources, a Contacts form, and an interactive photo gallery — introducing HTML forms, CSS Grid, and the first JavaScript in the series.

Introduction

In the previous article we organized FastURL — our open-source URL shortener — into clean layers: routers, services, repositories, and a dependency injection system that wires them together. The structure is in place; now we need to make it behave correctly at runtime.

Three things have to work right in any production FastAPI application that does non-trivial work:

• Async I/O must be used correctly so the event loop is never blocked.
• Background tasks must fire without delaying the HTTP response.
• Error handling must produce a predictable, machine-readable envelope for every possible failure.

This article covers all three, using FastURL as the concrete project.

You should read this article if:

• You understand async/await in Python but are unsure which handlers in FastAPI should be async def and which should be def.
• You want to implement fire-and-forget background work in FastAPI without introducing an external broker.
• You want a single, consistent error envelope across Pydantic validation failures, domain exceptions, and unhandled errors.

This article is part of the Modern Python Application series and the FastURL sub-series.

Async I/O in FastAPI: async def vs def

Think of a highway with a single lane: every vehicle must wait for the one in front to clear before it can move. A blocking route handler is that stuck vehicle — while it waits for a database query or an HTTP call to return, no other request can be processed. FastAPI runs on an async event loop — the same model we covered in depth in the asyncio article — so every await is a legal overtaking lane: the handler suspends, the event loop runs something else, and the handler resumes when the I/O is ready.

The rule is simple:

If a handler calls anything that involves I/O — database queries, outbound HTTP, file reads — declare it async def and await every call. If it does only CPU work, use plain def.

FastAPI handles both correctly. A plain def route is run in a thread pool so it does not block the event loop. An async def route runs directly on the loop. The mistake to avoid is mixing the two: an async def that calls a blocking library (like requests or synchronous SQLAlchemy) blocks the event loop entirely, stalling every other request in the process. If you are new to the concurrency model underlying this, the concurrency in Python article covers threads, processes, and the event loop side by side.

The table below maps the most common blocking operations to their async replacements:

If an existing library has no async version, wrap the blocking call in await asyncio.get_event_loop().run_in_executor(None, blocking_fn) to offload it to a thread pool without stalling the loop. The asyncio docs cover the full executor API.

In FastURL every route handler is async def because every one of them calls either the async repository (SQLAlchemy AsyncSession) or the background inspector (httpx.AsyncClient). Here is the create_link handler in full:

@router.post(
    path="",
    response_model=LinkResponse,
    status_code=status.HTTP_201_CREATED,
)
async def create_link(
    body: LinkCreateRequest,
    service: LinkServiceDep,
    http_client: HTTPClientDep,
    background_tasks: BackgroundTasks,
) -> LinkResponse:
    response: LinkResponse = await service.create_link(
        target_url=str(body.target_url),
        custom_code=body.custom_code,
        expires_at=body.expires_at,
    )
    background_tasks.add_task(
        func=inspect_link,
        code=response.code,
        target_url=response.target_url,
        http_client=http_client,
        repository=service._repository,
    )
    return response

await service.create_link(...) yields control to the event loop while the database insert is in flight. By the time the return statement executes, the link is persisted and the response is ready. The background inspection — which involves an outbound HTTP call to the target URL — is dispatched via BackgroundTasks and never blocks the response. More on that in the next section.

The shared httpx.AsyncClient

The http_client parameter above comes from app.state. Creating a new httpx.AsyncClient per request is the most common mistake in async FastAPI code: each new client opens a fresh connection pool, establishes a TCP handshake, and discards both when the request ends. With any meaningful traffic, you get hundreds of redundant connections per second. The httpx docs on connection pooling explain the mechanics in detail.

The right pattern is one shared client per application, created at startup and closed at shutdown. FastAPI’s lifespan context manager is exactly the right place for it:

from contextlib import asynccontextmanager
from collections.abc import AsyncIterator
import httpx
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    # --- Startup ---
    app.state.http_client = httpx.AsyncClient(
        timeout=httpx.Timeout(10.0),
        follow_redirects=True,
        max_redirects=5,
        headers={"User-Agent": "FastURL-Inspector/0.1"},
    )
    yield
    # --- Shutdown ---
    await app.state.http_client.aclose()

app = FastAPI(lifespan=lifespan)

Breaking down the httpx.AsyncClient options:

• timeout=httpx.Timeout(10.0) — caps the full request lifecycle (connect + read) at 10 seconds; without a timeout a hanging target URL would hold an open connection indefinitely
• follow_redirects=True — the inspector must reach the final destination to extract accurate metadata
• max_redirects=5 — prevents infinite redirect loops from consuming the client
• headers={"User-Agent": "..."} — many servers return 403 for requests that look like anonymous bots; a descriptive User-Agent prevents that class of silent failure

The client is retrieved inside a FastAPI dependency and injected into route handlers via HTTPClientDep:

def _get_http_client(request: Request) -> httpx.AsyncClient:
    return request.app.state.http_client

HTTPClientDep: TypeAlias = Annotated[httpx.AsyncClient, Depends(_get_http_client)]

One httpx.AsyncClient per application, opened in lifespan, closed on shutdown. Never create a client inside a route handler or a background task.

The full implementation is in main.py.

The shared database engine

The same principle applies to the SQLAlchemy async engine. The engine owns the connection pool — the set of persistent database connections that are checked out per request and returned when the session closes. Creating a new engine per request would open a fresh pool, perform the SQLite handshake, and discard both at the end of the request, identical to the httpx.AsyncClient mistake. We first introduced SQLAlchemy’s async session in the database layer article — see that article for the full ORM setup. The SQLAlchemy async docs cover engine and session lifecycle in depth.

The engine and session factory are created once at startup and disposed at shutdown inside two helpers, init_db() and close_db(), defined in database.py:

# database.py
from sqlalchemy.ext.asyncio import (
    AsyncEngine,
    AsyncSession,
    async_sessionmaker,
    create_async_engine,
)

_engine: AsyncEngine | None = None
_session_factory: async_sessionmaker[AsyncSession] | None = None

async def init_db() -> None:
    global _engine, _session_factory
    _engine = create_async_engine(url=settings.database.url, echo=settings.database.echo)
    _session_factory = async_sessionmaker(bind=_engine, class_=AsyncSession, expire_on_commit=False)
    async with _engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

async def close_db() -> None:
    global _engine
    if _engine is not None:
        await _engine.dispose()
        _engine = None

Both are called from the lifespan context manager in main.py:

# main.py
await init_db()   # startup
yield
await close_db()  # shutdown — engine.dispose() flushes and closes all pooled connections

The per-request session is a separate concern. A session is not safe to share across requests: it carries per-request transaction state and is not coroutine-safe. The get_db dependency opens a fresh session from the shared factory for every request and closes it automatically when the request ends:

async def get_db() -> AsyncIterator[AsyncSession]:
    async with _session_factory() as session:
        yield session

Calling _session_factory() is cheap — it checks out a connection from the pool that already exists in the engine; it does not open a new one. The pool is reused; only the session object is fresh.

This creates an important asymmetry between the two shared resources:

One AsyncEngine per application, opened in lifespan, disposed on shutdown. One AsyncSession per request, opened by get_db, closed after the request. Never share a session across requests.

The full implementation is in database.py.

Background Tasks: Fire-and-Forget Without a Broker

When a new link is created, FastURL must immediately return a 201 Created response to the caller. But it also needs to check the target URL’s health, record its HTTP status code and latency, and extract the HTML title and OpenGraph metadata. These operations take hundreds of milliseconds — far too long to include in the response cycle.

FastAPI’s BackgroundTasks solves this without any external infrastructure. A BackgroundTask is a coroutine (or a plain function) that FastAPI runs after the response has been sent to the client. The route handler returns immediately; the background work executes in the same event loop, after Starlette finishes streaming the response bytes.

background_tasks.add_task(
    func=inspect_link,
    code=response.code,
    target_url=response.target_url,
    http_client=http_client,
    repository=service._repository,
)

Breaking down the arguments:

• func=inspect_link — the coroutine function to run; FastAPI detects async def and awaits it automatically
• code and target_url — positional arguments forwarded to inspect_link
• http_client — the shared httpx.AsyncClient from app.state; the background task must reuse it, not create its own
• repository=service._repository — the LinkRepository instance, already bound to the current database session via dependency injection

What inspect_link does

inspect_link is a pure async function in inspector_service.py. It has zero FastAPI imports — it knows nothing about HTTP requests, response models, or routing. This is the key constraint that keeps the service layer testable:

async def inspect_link(
    code: str,
    target_url: str,
    http_client: httpx.AsyncClient,
    repository: LinkRepository,
) -> None:
    status = "unreachable"
    http_status_code: int | None = None
    latency_ms: float | None = None
    title: str | None = None
    description: str | None = None
    image_url: str | None = None

    start = time.monotonic()
    try:
        response = await http_client.get(target_url)
        latency_ms = round((time.monotonic() - start) * 1000, 2)
        http_status_code = response.status_code

        if response.is_success or response.is_redirect:
            status = "active"
            html = response.text
            title = _extract_title(html)
            description = _extract_description(html)
            image_url = _extract_image_url(html)
        else:
            status = "unreachable"

    except httpx.TimeoutException:
        latency_ms = round((time.monotonic() - start) * 1000, 2)

    except httpx.RequestError as exc:
        latency_ms = round((time.monotonic() - start) * 1000, 2)

    await repository.update_inspection(
        code,
        status=status,
        http_status_code=http_status_code,
        latency_ms=latency_ms,
        title=title,
        description=description,
        image_url=image_url,
    )

The try/except block covers two failure modes: httpx.TimeoutException for deadline expiry and httpx.RequestError for DNS failures, refused connections, and similar network-level errors. In both cases the status remains "unreachable" and the inspection result is persisted so the caller can see the link was checked but unreachable — rather than leaving the status permanently at "pending_analysis".

The metadata extraction uses three lightweight regex helpers — _extract_title, _extract_description, _extract_image_url — that parse the raw HTML string without adding a full parser dependency. They are pure synchronous functions: by the time they run, the HTTP response body is already in memory, so there is no I/O to await.

BackgroundTasks vs an external broker

BackgroundTasks is not a replacement for a job queue like Celery, RQ, or a message broker. The comparison is worth making explicit:

FastURL’s inspection task is a good fit for BackgroundTasks: losing an inspection on a crash is acceptable — the client can re-trigger it via POST /api/v1/links/{code}/inspect. A payment processing step or an email confirmation would not be acceptable candidates.

Error Handling: One Envelope for Every Failure

A client that calls a production API must be able to branch on the response without parsing human-readable text. The FastURL error contract guarantees this with a single JSON shape for every failure. The FastAPI exception handlers docs describe the default behaviour we are overriding here:

{
  "success": false,
  "error": "LINK_NOT_FOUND",
  "details": [
    "code -> No link found with code 'aB3x9zK'"
  ]
}

• success — always false on error; useful for clients that check this flag before parsing the body
• error — a machine-readable short code; clients branch on this field
• details — a list of human-readable, field-level explanations; used for logging and developer messages

Three global handlers registered in main.py cover every failure path.

Handler 1: Pydantic validation failures (400)

When FastAPI receives a request body or query parameter that fails Pydantic validation, it raises RequestValidationError. The default FastAPI behaviour returns a 422 Unprocessable Entity — but 422 is rarely what API clients expect for bad input. FastURL overrides this to 400 Bad Request:

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
    error_details: list[str] = []
    for e in exc.errors():
        loc = " -> ".join(str(x) for x in e["loc"])
        msg = e["msg"]
        error_details.append(f"{loc}: {msg}")
    return JSONResponse(
        status_code=400,
        content={"success": False, "error": "VALIDATION_ERROR", "details": error_details},
    )

exc.errors() returns a list of Pydantic error dicts. Each dict has a loc tuple (field path) and a msg string. The handler flattens the location into a readable "body -> target_url: value is not a valid URL" string and collects all errors into the details list — so a single response surfaces every validation failure at once, not just the first one.

Handler 2: Domain exceptions (4xx)

Domain exceptions are pure Python classes with zero FastAPI imports. They carry the HTTP status code and error payload, but they know nothing about JSONResponse or routing. The full set of exceptions lives in exceptions.py:

class AppError(Exception):
    def __init__(self, message: str, status_code: int = 400, details: list[str] | None = None) -> None:
        super().__init__(message)
        self.message = message
        self.status_code = status_code
        self.details: list[str] = details or []

class LinkNotFoundError(AppError):
    def __init__(self, code: str) -> None:
        super().__init__(
            message="LINK_NOT_FOUND",
            status_code=404,
            details=[f"code -> No link found with code '{code}'"],
        )

class LinkExpiredError(AppError):
    def __init__(self, code: str, expired_at: str) -> None:
        super().__init__(
            message="LINK_EXPIRED",
            status_code=410,
            details=[f"code -> Link '{code}' expired on {expired_at}"],
        )

The global handler converts any AppError subclass into the standard envelope:

@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
    return JSONResponse(
        status_code=exc.status_code,
        content={"success": False, "error": exc.message, "details": exc.details},
    )

The service layer raises LinkNotFoundError, AliasAlreadyTakenError, or LinkExpiredError without ever importing FastAPI. The HTTP layer sees the exception, the handler serialises it, the client gets a consistent envelope. The layers stay clean.

Handler 3: Unhandled exceptions (500)

The third handler is the safety net. Any exception that escapes the service and repository layers — a database connection drop, a bug, an unexpected None — reaches this handler. It logs the full traceback server-side and returns a generic message to the client:

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
    tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
    logger.error(f"Unhandled exception at {request.url}:\n{tb}")
    return JSONResponse(
        status_code=500,
        content={
            "success": False,
            "error": "INTERNAL_SERVER_ERROR",
            "details": ["An unexpected error occurred. Please contact support."],
        },
    )

The traceback goes to the server log — never to the client. Leaking stack traces to API consumers is an information disclosure vulnerability: it reveals internal class names, file paths, and sometimes configuration values. The client sees only the generic message and the correlation ID header (X-Request-ID) that makes the server log entry findable.

The complete handler mapping

The full registration of all three handlers is in exceptions.py.

Conclusion

In this article we covered:

• Why every I/O-bound route handler must be async def and why mixing async def with blocking libraries stalls the entire event loop.
• How to create a single shared httpx.AsyncClient in the FastAPI lifespan context and inject it via a dependency — and why creating a client per request destroys connection pooling.
• How the same principle applies to the SQLAlchemy AsyncEngine: one engine per application, opened in lifespan, disposed on shutdown — with a fresh AsyncSession per request opened by the get_db dependency.
• How BackgroundTasks runs inspect_link after the 201 Created response is sent, keeping the HTTP cycle fast while the background work happens asynchronously in the same process.
• When BackgroundTasks is the right tool and when an external broker is necessary — durability, retry policies, and scale are the deciding factors.
• How three global exception handlers produce a single {success, error, details} envelope for Pydantic validation failures, domain exceptions, and unhandled errors — with no stack traces leaking to clients.

The next article in the Modern Python Application series will go deeper into testing patterns for Python applications — pytest fixtures, async tests, and coverage strategies for real production code.

Introduction

In the previous article we defined the domain model and API contract for FastURL, our open-source URL shortener and link inspector service hosted on GitHub. We established how requirements turn into domain entities, how Pydantic v2 schemas act as Value Objects, and how a consistent error envelope isolates clients from internal failure mechanics.

Designing endpoints and validation rules is essential, but code needs a clean home to live in. If you put database queries, HTTP handling, business validation, and external network requests into a single route function, your application will quickly turn into an unmaintainable monolith. We previously explored structuring a database layer with SQLAlchemy and managing asyncio event loop concurrency; now we bring those principles together in an API context.

This article shows how to organize a real-world FastAPI application into clean, isolated layers: Routers, Services, and Repositories, connected together seamlessly through FastAPI’s Dependency Injection system.

You should read this article if:

• You want to structure a production-grade FastAPI codebase beyond trivial single-file tutorials.
• You want to decouple business logic from HTTP frameworks and database ORMs.
• You want to master async SQLAlchemy 2.0 repositories and FastAPI dependency injection (Depends).

The Problem with Fat Route Handlers

Imagine an endpoint that receives a URL shortening request, checks database duplicates, executes an insert, sends a background notification, and formats the JSON response all within the same 50-line route function.

While this works for simple scripts, it fails in production:

1. No reusability: If a background worker or CLI needs to shorten a URL, it cannot reuse the route logic without importing HTTP request objects.
2. Untestable logic: Unit testing business rules requires spinning up mock HTTP clients and a live database instance.
3. Leaky abstractions: The HTTP layer is tightly coupled to database schema details, table column names, and ORM session states.

To prevent this decay, we structure FastURL using a classic Layered Architecture.

The dependency arrow points strictly downward: Routers depend on Services, and Services depend on Repositories. Lower layers never know about the layers above them.

Real Project Folder Structure

Here is how the FastURL codebase is organized inside src/fasturl/:

fasturl/
├── config.yaml                # Application configuration file
├── pyproject.toml             # Dependencies and build configuration (uv / PEP 621)
├── sql/
│   └── schema.sql             # Reference SQL schema definition
├── src/
│   └── fasturl/
│       ├── api/               # Router layer: endpoints, schemas, dependencies
│       │   ├── dependencies/  # FastAPI dependency providers (Depends factories)
│       │   ├── middleware/    # HTTP middleware (CORS, error handling, etc.)
│       │   ├── routers/       # APIRouter definitions (links, redirect)
│       │   └── schemas/       # Pydantic request and response DTO schemas
│       ├── core/              # Cross-cutting: configuration, logging, database, exceptions
│       │   ├── config/        # Pydantic Settings modules (app, db, log, inspector)
│       │   ├── database.py    # Async SQLAlchemy engine & session factory
│       │   ├── exceptions.py  # Domain error hierarchy (AppError, ValidationError, etc.)
│       │   └── log.py         # Loguru structured logging configuration
│       ├── models/            # SQLAlchemy ORM models (table mappings)
│       │   └── link.py
│       ├── repositories/      # Data access layer (async repositories)
│       │   └── link_repository.py
│       ├── services/          # Business logic layer (LinkService, InspectorService)
│       │   ├── inspector_service.py
│       │   └── link_service.py
│       └── main.py            # FastAPI application factory, lifespan, router registration
└── tests/
    ├── unit/                  # Fast isolated unit tests (mocked repositories)
    └── integration/           # End-to-end HTTP tests with TestClient and SQLite

Each module has a clearly delineated responsibility:

• models/: Houses SQLAlchemy declarative ORM mappings.
• repositories/: Contains classes that handle raw SQL operations and query execution using AsyncSession.
• services/: Encapsulates pure domain workflows and business rules. Free of any HTTP framework dependencies.
• api/: Contains FastAPI routers, input/output schemas (DTOs), and dependency injection wiring.
• core/: Provides infrastructure foundations:
  • config/: Type-safe settings with Pydantic Settings across application, database, and logging domains.
  • database.py: Async SQLAlchemy session lifecycle and engine initialization, expanding on our SQLAlchemy database layer.
  • log.py: Structured application logging with Loguru.
  • exceptions.py: Clean domain error hierarchy (AppError, ValidationError, LinkNotFoundError).

Domain Model Mapping: Embedding Value Objects in the ORM

In FastURL’s domain design, the Link entity is the Aggregate Root. Its Value Objects — ShortCode, TargetUrl, LinkInspection, and LinkMetrics — do not have separate lifecycle identities.

In the database, we map this domain structure to a clean single-table schema (links), embedding the Value Object properties as flat columns.

Here is the SQLAlchemy 2.0 ORM model in src/fasturl/models/link.py:

from datetime import UTC, datetime
from sqlalchemy import Boolean, DateTime, Float, Integer, String, Text
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase):
    """Shared declarative base for all ORM models."""

class Link(Base):
    __tablename__ = "links"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    code: Mapped[str] = mapped_column(String(length=16), nullable=False, unique=True, index=True)
    target_url: Mapped[str] = mapped_column(Text, nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
    expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True, default=None)

    # LinkInspection Value Object — embedded columns
    inspection_status: Mapped[str] = mapped_column(String(length=20), nullable=False, default="pending_analysis")
    http_status_code: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
    latency_ms: Mapped[float | None] = mapped_column(Float, nullable=True, default=None)
    title: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
    description: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
    image_url: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
    last_checked_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True, default=None)

    # LinkMetrics Value Object — embedded columns
    clicks_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
    last_clicked_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True, default=None)

    # Audit timestamps
    created_at: Mapped[datetime] = mapped_column(
        DateTime, nullable=False, default=lambda: datetime.now(UTC).replace(tzinfo=None)
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime,
        nullable=False,
        default=lambda: datetime.now(UTC).replace(tzinfo=None),
        onupdate=lambda: datetime.now(UTC).replace(tzinfo=None),
    )

Notice a key design decision: the surrogate primary key id is internal only. The sole public identifier is code (the 7–16 character Base62 string), which is indexed and unique.

The Repository Layer: Async Data Access

The Repository (LinkRepository in src/fasturl/repositories/link_repository.py) has a single job: encapsulate SQL operations using SQLAlchemy’s async engine. It contains no business logic, no status code definitions, and no pricing rules.

from datetime import UTC, datetime
from sqlalchemy import func, select, update
from sqlalchemy.engine.result import Result
from sqlalchemy.ext.asyncio import AsyncSession
from fasturl.models.link import Link

class LinkRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session

    async def get_by_code(self, code: str) -> Link | None:
        """Return the Link with the given code, or None if not found."""
        result: Result[Link] = await self._session.execute(
            select(Link).where(Link.code == code)
        )
        return result.scalar_one_or_none()

    async def create(self, link: Link) -> Link:
        """Persist a new Link record and return the refreshed instance."""
        self._session.add(instance=link)
        await self._session.commit()
        await self._session.refresh(instance=link)
        return link

    async def soft_delete(self, code: str) -> bool:
        """Set is_active = False for the link with the given code."""
        result: Result[int] = await self._session.execute(
            update(table=Link)
            .where(Link.code == code)
            .values(is_active=False, updated_at=datetime.now(UTC).replace(tzinfo=None))
            .returning(Link.id)
        )
        await self._session.commit()
        return result.scalar_one_or_none() is not None

    async def increment_clicks(self, code: str) -> None:
        """Atomically increment clicks_count and update last_clicked_at."""
        await self._session.execute(
            update(Link)
            .where(Link.code == code)
            .values(
                clicks_count=Link.clicks_count + 1,
                last_clicked_at=func.now(),
                updated_at=func.now(),
            )
        )
        await self._session.commit()

    async def code_exists(self, code: str) -> bool:
        """Return True if any link uses the given code."""
        result: Result[int] = await self._session.execute(
            select(Link.id).where(Link.code == code)
        )
        return result.scalar_one_or_none() is not None

All methods are fully asynchronous and use type-safe SQLAlchemy 2.0 select and update constructs. Notice that updates like increment_clicks use database-level atomic increments (clicks_count = Link.clicks_count + 1) to eliminate race conditions under concurrent traffic.

The Service Layer: Pure Business Logic

The Service layer (LinkService in src/fasturl/services/link_service.py) is the brain of the application. It orchestrates business workflows, generates random Base62 codes, handles code collision retries, and raises domain exceptions.

Crucially, LinkService has zero knowledge of FastAPI or HTTP. It does not import Request, Response, or HTTPException.

import random
import string
from datetime import UTC, datetime
from loguru import logger
from fasturl.api.schemas.link_schemas import LinkResponse, InspectionResponse, MetricsResponse
from fasturl.core.config import settings
from fasturl.core.exceptions import AliasAlreadyTakenError, LinkExpiredError, LinkNotFoundError, ValidationError
from fasturl.models.link import Link
from fasturl.repositories.link_repository import LinkRepository

_log = logger.bind(name="LinkService")
_BASE62_ALPHABET = string.ascii_letters + string.digits
_MAX_CODE_RETRIES = 10

class LinkService:
    def __init__(self, repository: LinkRepository) -> None:
        self._repository = repository

    def _generate_code(self) -> str:
        """Generate a random Base62 code of the configured length."""
        length = settings.app.code_length
        return "".join(random.choices(_BASE62_ALPHABET, k=length))

    def _validate_target_url(self, target_url: str) -> None:
        """Enforce self-redirect loop prevention."""
        base = settings.app.base_url.rstrip("/").lower()
        if target_url.lower().startswith(base):
            raise ValidationError(["target_url -> URL must not point back to this service (self-redirect)"])

    async def create_link(
        self,
        target_url: str,
        custom_code: str | None,
        expires_at: datetime | None,
    ) -> LinkResponse:
        """Create a new shortened link, checking collisions and invariants."""
        self._validate_target_url(target_url)

        if custom_code is not None:
            if await self._repository.code_exists(code=custom_code):
                raise AliasAlreadyTakenError(alias=custom_code)
            code: str = custom_code
        else:
            # Collision-retry loop for auto-generated codes
            for _ in range(_MAX_CODE_RETRIES):
                candidate = self._generate_code()
                if not await self._repository.code_exists(code=candidate):
                    code = candidate
                    break
            else:
                _log.error("Failed to generate a unique code after max retries")
                raise ValidationError(["code -> Could not generate a unique short code. Please try again."])

        now: datetime = datetime.now(UTC).replace(tzinfo=None)
        link = Link(
            code=code,
            target_url=target_url,
            is_active=True,
            expires_at=expires_at,
            inspection_status="pending_analysis",
            clicks_count=0,
            created_at=now,
            updated_at=now,
        )
        persisted = await self._repository.create(link)
        _log.info(f"Link created: code='{code}', target='{target_url}'")
        return self._orm_to_response(persisted)

    async def resolve_for_redirect(self, code: str) -> str:
        """Resolve a short code for redirect, validating active status and expiry."""
        link = await self._repository.get_by_code(code)
        if link is None or not link.is_active:
            raise LinkNotFoundError(code)

        if link.expires_at is not None:
            expires = link.expires_at.replace(tzinfo=None) if link.expires_at.tzinfo else link.expires_at
            if datetime.now(UTC).replace(tzinfo=None) > expires:
                raise LinkExpiredError(code, expired_at=link.expires_at.isoformat())

        return link.target_url

    def _orm_to_response(self, link: Link) -> LinkResponse:
        base = settings.app.base_url.rstrip("/")
        return LinkResponse(
            code=link.code,
            short_url=f"{base}/{link.code}",
            target_url=link.target_url,
            is_active=link.is_active,
            expires_at=link.expires_at,
            inspection=InspectionResponse(
                status=link.inspection_status,
                http_status_code=link.http_status_code,
                latency_ms=link.latency_ms,
                title=link.title,
                description=link.description,
                image_url=link.image_url,
                last_checked_at=link.last_checked_at,
            ),
            metrics=MetricsResponse(
                clicks_count=link.clicks_count,
                last_clicked_at=link.last_clicked_at,
            ),
            created_at=link.created_at,
            updated_at=link.updated_at,
        )

Because LinkService takes LinkRepository in its constructor, testing business logic becomes trivial. In unit tests, you can inject a mock repository without needing a running database or HTTP server.

The Router Layer: Thin Handlers and HTTP Contracts

The Router layer (src/fasturl/api/routers/links.py and redirect.py) is responsible strictly for HTTP concerns: routing paths, status codes, query/body parameter parsing, and dispatching background tasks.

1. Management Endpoints (/api/v1/links)

from typing import Annotated, TypeAlias
from fastapi import APIRouter, BackgroundTasks, Path, status
from fasturl.api.dependencies import HTTPClientDep, LinkServiceDep
from fasturl.api.schemas.link_schemas import LinkCreateRequest, LinkResponse
from fasturl.services.inspector_service import inspect_link

router = APIRouter(prefix="/api/v1/links", tags=["Links"])

_CodePath: TypeAlias = Annotated[
    str,
    Path(min_length=7, max_length=16, description="Base62 short code or alias"),
]

@router.post(
    path="",
    response_model=LinkResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Create a new shortened link",
)
async def create_link(
    body: LinkCreateRequest,
    service: LinkServiceDep,
    http_client: HTTPClientDep,
    background_tasks: BackgroundTasks,
) -> LinkResponse:
    """Create link and dispatch non-blocking background inspection."""
    response = await service.create_link(
        target_url=str(body.target_url),
        custom_code=body.custom_code,
        expires_at=body.expires_at,
    )
    background_tasks.add_task(
        func=inspect_link,
        code=response.code,
        target_url=response.target_url,
        http_client=http_client,
        repository=service._repository,
    )
    return response

@router.get(
    path="/{code}",
    response_model=LinkResponse,
    status_code=status.HTTP_200_OK,
    summary="Retrieve single link details",
)
async def get_link(code: _CodePath, service: LinkServiceDep) -> LinkResponse:
    return await service.get_link(code)

2. Public Redirect Endpoint (/{code})

The redirect endpoint in src/fasturl/api/routers/redirect.py lives at the root URL (without /api/v1):

from fastapi import APIRouter, BackgroundTasks
from fastapi.responses import RedirectResponse
from fasturl.api.dependencies import LinkServiceDep

router = APIRouter(tags=["Redirect"])

@router.get(
    path="/{code}",
    status_code=307,
    response_class=RedirectResponse,
    summary="Resolve and redirect short URL",
)
async def redirect_short_url(
    code: str,
    service: LinkServiceDep,
    background_tasks: BackgroundTasks,
) -> RedirectResponse:
    """Resolve short code and issue 307 redirect; record clicks in background."""
    target_url = await service.resolve_for_redirect(code)

    # Click counter increment happens non-blockingly after response is returned
    background_tasks.add_task(
        func=service._repository.increment_clicks,
        code=code,
    )

    return RedirectResponse(url=target_url, status_code=307)

Notice that 307 Temporary Redirect is chosen instead of 301 Moved Permanently. A 301 redirect is aggressively cached by web browsers, which would prevent the server from tracking subsequent clicks for the same user.

Deep Dive: Dependency Injection in FastAPI

What Is Dependency Injection?

Imagine you are assembling a desktop computer. If the CPU was permanently soldered to the power supply and hardwired to a specific monitor, replacing the monitor or testing the CPU in isolation would be impossible. Instead, standard sockets and cables decouple each component: the power supply plugs in where electricity is needed, and the monitor plugs into the video port.

In software, Dependency Injection (DI) is that exact plug-and-socket design.

Without Dependency Injection, a class or function creates its own dependencies internally:

# Anti-pattern: Hardcoded dependency creation (tight coupling)
class LinkService:
    def __init__(self) -> None:
        # LinkService is tightly coupled to AsyncSession and sqlite:///fasturl.db
        self.session = create_async_session("sqlite+aiosqlite:///instance/fasturl.db")
        self.repository = LinkRepository(self.session)

With Dependency Injection, an object receives its dependencies from an outside provider rather than instantiating them itself:

# Clean pattern: Dependency Injection via constructor
class LinkService:
    def __init__(self, repository: LinkRepository) -> None:
        self._repository = repository

LinkService no longer cares how LinkRepository is created, which database connection string was used, or whether it’s talking to PostgreSQL, SQLite, or an in-memory mock during tests.

Why Is Dependency Injection Essential?

Dependency Injection solves four critical software architecture challenges:

1. Unit Testing without Database or Network Overheads: When writing tests for LinkService, you do not want to start a database engine, run migrations, or clean up test records. You can instantiate LinkService(MockLinkRepository()) directly and verify domain logic in milliseconds.
2. Deterministic Resource Lifecycles (Session Scoping): Database sessions, connection pools, and HTTP clients must be opened before a request starts and safely closed (or rolled back) when the request finishes. DI automates this teardown per request without polluting business functions with try-finally blocks.
3. Inversion of Control (IoC): High-level modules (business services) do not depend on low-level implementation details (SQLAlchemy engines). Both depend on abstractions.
4. Declarative and Type-Safe Route Signatures: With Python type hints and FastAPI Annotated, handlers state what they need in their signature, and the framework resolves the dependency graph.

How FastAPI Resolves the Dependency Graph with Depends

FastAPI provides a first-class DI system via Depends. In FastURL, the entire dependency graph is wired in src/fasturl/api/dependencies/__init__.py:

from typing import Annotated, TypeAlias
import httpx
from fastapi import Depends, Request
from sqlalchemy.ext.asyncio import AsyncSession
from fasturl.core.database import get_db
from fasturl.repositories.link_repository import LinkRepository
from fasturl.services.link_service import LinkService

# 1. Yields an AsyncSession per request and guarantees cleanup
DBSessionDep: TypeAlias = Annotated[AsyncSession, Depends(dependency=get_db)]

# 2. Reuses the shared httpx.AsyncClient stored in FastAPI app.state during lifespan
def _get_http_client(request: Request) -> httpx.AsyncClient:
    return request.app.state.http_client

HTTPClientDep: TypeAlias = Annotated[httpx.AsyncClient, Depends(dependency=_get_http_client)]

# 3. Builds a LinkRepository scoped to the active database session
def _get_link_repository(session: DBSessionDep) -> LinkRepository:
    return LinkRepository(session)

LinkRepoDep: TypeAlias = Annotated[LinkRepository, Depends(dependency=_get_link_repository)]

# 4. Builds LinkService injected with LinkRepository
def _get_link_service(repository: LinkRepoDep) -> LinkService:
    return LinkService(repository=repository)

LinkServiceDep: TypeAlias = Annotated[LinkService, Depends(dependency=_get_link_service)]

The Request Execution Flow

When an HTTP request reaches POST /api/v1/links:

@router.post("")
async def create_link(
    body: LinkCreateRequest,
    service: LinkServiceDep,
    http_client: HTTPClientDep,
    background_tasks: BackgroundTasks,
) -> LinkResponse:
    ...

FastAPI automatically traverses and resolves the dependency hierarchy:

Overriding Dependencies in Integration Tests

One of the greatest benefits of FastAPI’s DI engine is app.dependency_overrides. In integration tests, you can replace any provider in the chain without changing application code:

from fastapi.testclient import TestClient
from fasturl.api.dependencies import _get_link_service
from fasturl.main import app

def test_create_link_with_mocked_service():
    # Override LinkService with a mock or test instance
    app.dependency_overrides[_get_link_service] = lambda: FakeLinkService()

    client = TestClient(app)
    response = client.post("/api/v1/links", json={"target_url": "https://example.com"})

    assert response.status_code == 201
    
    # Clean up overrides after test
    app.dependency_overrides.clear()

Architectural Summary

By enforcing strict boundaries across layers, each part of FastURL has a singular focus:

Conclusion

In this article we covered:

• The Layered Architecture pattern: how organizing code into Routers, Services, and Repositories prevents codebase decay and creates clean separation of concerns.
• The FastURL project structure: how api/, services/, repositories/, models/, and core/ packages separate responsibilities cleanly.
• Domain model to ORM mapping: mapping the Link Aggregate Root and embedded Value Objects to flat SQLAlchemy 2.0 table columns.
• Async Repository pattern: executing queries, atomic increments, and soft-deletions using AsyncSession.
• Pure business services: generating Base62 short codes, verifying self-redirect invariants, and raising domain exceptions without HTTP coupling.
• Dependency Injection: constructing automated per-request dependency graphs using FastAPI’s Depends and typed Annotated aliases.

The next article covers advanced operational features in FastAPI: async background tasks, managing shared HTTP connection pools with httpx.AsyncClient in lifespan context, and global exception handlers.

Introduction

In the previous article we established the theory: requirements produce domain entities, domain entities become REST resources, and HTTP methods map to the lifecycle operations of those resources. Kubernetes was the illustration — large enough to make the pattern clear, but too complex to implement in a blog post.

This article moves from theory to practice. The project is FastURL, a URL shortener and link inspector built with FastAPI. It is small enough to fit comfortably in a few articles, but real enough to demonstrate every concept that matters: domain modeling, Pydantic validation as a form of type-safe Value Objects, a standardized error envelope, and a resource hierarchy derived directly from the domain.

You should read this article if:

• You have read the previous article and want to see the methodology applied to real code.
• You want to understand how Pydantic v2 validators enforce domain rules at the HTTP boundary.
• You want to see how a consistent error contract is designed and implemented from scratch.

What FastURL Does

FastURL is a REST API that shortens long URLs into compact 7-character codes and resolves them back via HTTP redirects. Beyond basic shortening, it runs an asynchronous background inspection on every newly created link: it fetches the target page, records the HTTP status code and latency, and extracts the HTML title and OpenGraph metadata.

Three actors interact with the system:

This actor breakdown comes directly from the requirements document — before any code was written. The nouns in the job stories (Link, ShortCode, TargetUrl, Inspection, Metrics) became the domain entities. The verbs (shorten, resolve, inspect, delete) became the operations.

From Requirements to Domain Entities

Every requirement in FastURL can be traced to one of eight job stories documented in the requirements document. Three of them are worth looking at closely because they drive the entire domain design.

JS-001 — When I provide a valid target URL, I want a unique shortened URL with a random alphanumeric code. This story introduces two domain concepts: a Link (the association between a short code and a target URL) and a ShortCode (a validated 7-character Base62 string). The story also establishes a business rule: the code must be unique and collision-resistant.

JS-006 — When I navigate to a short URL, I want to be redirected immediately. This story adds two more rules: the link must be active (is_active = true) and must not have passed its expiration date (expires_at). If either condition fails, the redirect must not happen.

JS-007 — When a new link is registered, I want a non-blocking background check on the target URL. This story introduces the LinkInspection concept: a snapshot of target URL health, latency, and page metadata. Crucially, it must not block the creation response — the system acknowledges the creation immediately and inspects asynchronously. This is the async I/O pattern we covered earlier in the series.

These three stories alone define the core of the domain model.

The Domain Model

FastURL has a single Aggregate Root: Link. It owns all the data and enforces all invariants. The Value Objects — ShortCode, TargetUrl, LinkMetrics, and LinkInspection — are part of the Link aggregate, not separate entities with their own identity.

Link (Aggregate Root)
├── code          ← ShortCode (Base62, 7–16 chars, unique)
├── target_url    ← TargetUrl (HTTP/HTTPS only, no self-redirect)
├── is_active     ← soft-delete flag
├── expires_at    ← optional expiry
├── inspection    ← LinkInspection (status, latency, title, og:*)
└── metrics       ← LinkMetrics (clicks_count, last_clicked_at)

There are two bounded contexts: LinkManagement (CRUD and redirect resolution) and LinkInspection (async health check and metadata extraction). They communicate via a LinkCreated event that triggers the background task.

A single aggregate with Value Objects as members keeps the domain model flat and readable. LinkInspection and LinkMetrics have no identity of their own — they only make sense as part of a Link.

Mapping Entities to Resources

The mapping from domain to REST is direct:

Notice that /{code} carries no /api/v1/ prefix. This is intentional: it is a consumer-facing URL that must be short and stable, not a versioned management endpoint.

The POST /api/v1/links/{code}/inspect endpoint does not map to a CRUD operation — it triggers an action. As discussed in the previous article, POST is the correct method for non-CRUD actions on a resource.

Pydantic as Value Object Implementation

In Domain-Driven Design, a Value Object encapsulates validation rules and equality semantics. In FastAPI, Pydantic models serve exactly this role at the HTTP boundary. The LinkCreateRequest schema enforces every business rule on inbound data before the service layer is ever called.

class LinkCreateRequest(BaseModel):
    target_url: HttpUrl = Field(
        description="Destination URL to shorten. Must be HTTP or HTTPS.",
    )
    custom_code: str | None = Field(
        default=None,
        min_length=7,
        max_length=16,
    )
    expires_at: datetime | None = Field(default=None)

    @field_validator("custom_code")
    @classmethod
    def validate_custom_code(cls, v: str | None) -> str | None:
        if v is not None and not _BASE62_PATTERN.match(v):
            raise ValueError("custom_code must contain only alphanumeric characters [a-zA-Z0-9]")
        return v

    @model_validator(mode="after")
    def validate_expires_at_future(self) -> LinkCreateRequest:
        if self.expires_at is not None:
            now = datetime.now(UTC).replace(tzinfo=None)
            expires = self.expires_at.replace(tzinfo=None)
            if expires <= now:
                raise ValueError("expires_at -> Expiration date must be in the future")
        return self

Breaking down what each element enforces:

• HttpUrl — Pydantic’s built-in type rejects any URL that is not HTTP or HTTPS. No custom validator needed for the scheme.
• @field_validator — Enforces the Base62 alphabet rule: only [a-zA-Z0-9]. This is the ShortCode Value Object’s constraint, expressed as a Pydantic field-level validator.
• @model_validator(mode="after") — Runs after all fields are validated, so it can access self.expires_at. It rejects expiration dates in the past. This is a cross-field invariant that requires the full model context.

The response schema mirrors the domain structure: LinkResponse embeds InspectionResponse and MetricsResponse, reflecting the LinkInspection and LinkMetrics Value Objects in the aggregate.

class LinkResponse(BaseModel):
    code: str
    short_url: str
    target_url: str
    is_active: bool
    expires_at: datetime | None = None
    inspection: InspectionResponse
    metrics: MetricsResponse
    created_at: datetime
    updated_at: datetime

Note that id — the internal surrogate key — is absent from the response. The code is the sole public identifier. This is a deliberate design choice: a sequential integer PK is enumerable and guessable; a Base62 7-character code is not.

The Error Envelope

One of the most important consistency decisions in any API is the error contract. FastURL uses a single envelope for every error response:

{
  "success": false,
  "error": "LINK_NOT_FOUND",
  "details": [
    "code -> No link found with code 'aB3x9zK'"
  ]
}

The error field is a machine-readable short code. The details list contains human-readable, field-level explanations. This structure lets clients branch on error programmatically and display details to a developer or end user.

Domain Exceptions

Domain exceptions are pure Python classes — no FastAPI imports, no HTTP knowledge. They carry only the data needed to build the error response.

class LinkNotFoundError(AppError):
    def __init__(self, code: str) -> None:
        super().__init__(
            message="LINK_NOT_FOUND",
            status_code=404,
            details=[f"code -> No link found with code '{code}'"],
        )

class AliasAlreadyTakenError(AppError):
    def __init__(self, alias: str) -> None:
        super().__init__(
            message="ALIAS_ALREADY_TAKEN",
            status_code=409,
            details=[f"custom_code -> The alias '{alias}' is already in use"],
        )

class LinkExpiredError(AppError):
    def __init__(self, code: str, expired_at: str) -> None:
        super().__init__(
            message="LINK_EXPIRED",
            status_code=410,
            details=[f"code -> Link '{code}' expired on {expired_at}"],
        )

The AppError base class holds the message, status_code, and details. Subclasses just set the right values in __init__. The service layer raises these exceptions; the HTTP layer never needs to know how they are structured.

Global Exception Handlers

Three handlers registered in main.py cover every failure path:

def register_exception_handlers(app: FastAPI) -> None:

    @app.exception_handler(RequestValidationError)
    async def validation_exception_handler(request, exc) -> JSONResponse:
        error_details = []
        for e in exc.errors():
            loc = " -> ".join(str(x) for x in e["loc"])
            msg = e["msg"]
            error_details.append(f"{loc}: {msg}")
        return JSONResponse(
            status_code=400,
            content={"success": False, "error": "VALIDATION_ERROR", "details": error_details},
        )

    @app.exception_handler(AppError)
    async def app_error_handler(request, exc) -> JSONResponse:
        return JSONResponse(
            status_code=exc.status_code,
            content={"success": False, "error": exc.message, "details": exc.details},
        )

    @app.exception_handler(Exception)
    async def global_exception_handler(request, exc) -> JSONResponse:
        # Full traceback logged server-side; generic message returned to client
        return JSONResponse(
            status_code=500,
            content={"success": False, "error": "INTERNAL_SERVER_ERROR",
                     "details": ["An unexpected error occurred. Please contact support."]},
        )

The three handlers map precisely to the three failure categories:

The third handler is the safety net. It logs the full traceback server-side but returns only a generic message to the client — no stack traces, no internal details, no information disclosure.

The Full Endpoint Table

Bringing everything together, here is the complete API surface of FastURL:

A few design decisions worth noting:

• DELETE returns 204 No Content — no body, because there is nothing meaningful to return after a deletion.
• POST /api/v1/links/{code}/inspect returns 202 Accepted — not 200 OK. The inspection runs asynchronously; the client receives the current snapshot immediately and polls GET /api/v1/links/{code} for the result.
• GET /{code} can return 410 Gone for expired links. 410 is semantically different from 404: it signals that the resource existed but is permanently unavailable, not that it was never found.

Conclusion

In this article we covered:

• From job stories to domain entities: how the nouns and verbs in requirements directly produce the Link aggregate, the ShortCode and TargetUrl Value Objects, and the LinkInspection and LinkMetrics embedded snapshots.
• Pydantic as Value Object implementation: using HttpUrl, @field_validator, and @model_validator to enforce domain invariants at the HTTP boundary — before the service layer is called.
• A consistent error envelope: a single {success, error, details} structure for every failure, backed by domain exceptions that carry no HTTP knowledge and three global handlers that translate them.
• Resource hierarchy derived from the domain: five management endpoints plus a public redirect endpoint, each with a clear ownership and a precise set of status codes.

The next article walks through the layered code structure that makes all of this work: how routers, services, repositories, and the dependency injection system are organized to keep each concern in its own place.

Introduction

In the previous installments of this series, we explored CLI application patterns with Click and Typer. While CLI interfaces offer a convenient way for developers to interact with services locally, building distributed applications requires exposing services over the network via structured HTTP interfaces.

When designing a REST API, engineers often focus on choosing the “right” framework — FastAPI, Spring Boot, and so on. Tools matter, but they solve only the implementation detail. The real challenge is designing an API that reflects the business domain, exposes domain entities as resources, and uses HTTP semantics consistently, including errors and status codes.

Think of an API as a contract between two systems. As the designer of this contract, you act like a notary, carefully drafting the terms of interaction. However, this contract must follow the rules of HTTP, ensuring it adheres to the standard conventions for communication.

The first step is to identify the entities involved in the contract. Once these entities are clear, the next step is to define the rules: what operations can be performed on each entity, and under what conditions, all while respecting the HTTP framework.

A good API should be intuitive, self-describing, and coherent with the domain. This requires identifying business entities, their lifecycle, and their relationships before thinking about technology. Once the domain model is clear, the API becomes almost a direct consequence of it.

To avoid remaining purely theoretical, we will use Kubernetes as a case study. It provides a concrete example where functional requirements naturally lead to entities and operations that are directly exposed through an HTTP interface.

You should read this article if:

• You are designing or refactoring a REST API and want a rigorous, entity-driven methodology.
• You want to understand how domain concepts translate into REST resources, HTTP methods, and status codes.
• You want to see how Kubernetes models its complex architecture cleanly using standard REST conventions.

From requirements to entities: the logical model of Kubernetes

In a Clean Architecture perspective, the design process begins from the inside: entities at the center, then use cases, then the external interfaces.

Clean Architecture Main Concepts

User stories play a fundamental role here. They describe what the system must accomplish from a business perspective, and in doing so they implicitly define the domain language: the nouns in the stories become the entities of the domain, while the verbs describe the operations and relationships between them.

Kubernetes is no exception. Its functional requirements — scheduling workloads, distributing containers, maintaining stable network access, scaling services, enforcing security boundaries — naturally give rise to a set of domain entities. These entities exist independently of any API design choice; the API merely exposes them.

In this section, I assume the requirements of Kubernetes are already known and focus directly on their consequences: the entities that form the system and the relationships between them.

Resource entities

Kubernetes Entities with their Relationships

In Kubernetes everything is a Resource. Conceptually, Kubernetes exposes two main categories of resources:

• Namespaced resources — exist within a specific namespace
• Cluster-scoped resources — global across the entire cluster

Although the “cluster” itself is not a first-class API object, we can treat it as the top-level element for reasoning about relationships.

• A cluster consists of one or more nodes or workers.
• Each node runs one or more *Pods+.
• Each Pod contains one or more containers.

Pods are ephemeral and their network identity is unstable. For this reason, Pods are typically exposed through a Service (namespaced resource). Services come in three main variants:

• ClusterIP
• NodePort
• LoadBalancer

Workloads are created and managed by Workload (this concept doesn’t explicitly exist in Kubernetes but it helps us to model the resources). The most common ones are:

• Deployments, used for stateless applications
• StatefulSets, used for stateful applications
• DaemonSets, used to run one Pod instance on every (or selected) node
• Jobs, used for finite, one-off batch operations
• CronJobs, used for scheduled batch workloads

Pods may rely on persistent storage. They reference one or more PersistentVolumeClaims (PVCs), each of which binds to a PersistentVolume (PV) in a one-to-one manner.

Finally, users are not represented by Kubernetes YAML objects but are defined in the Kubernetes configuration (commonly via the kubeconfig file). Users acquire permissions through Roles (namespaced) and ClusterRoles (cluster-scoped). Roles are connected to users through RoleBindings or ClusterRoleBindings, depending on the scope.

Once this entity model is clear, designing a RESTful API becomes almost mechanical. Each entity maps directly to a resource, operations correspond to the entity’s lifecycle, and access control follows from the relationships defined in the domain model.

Defining the Rules of an API

Once we have identified the entities in the system, the next step is to define the rules of interaction between these entities. These rules will dictate how resources can be accessed, manipulated, or deleted via the API. Each rule can be broken down into four main components:

Defining the Rules of an API

1. Endpoint

The endpoint is the URL pattern that maps to the entity and defines the resource’s location. It is the path that the client will use to access the resource or perform an action on it.

A few important principles:

Use plural names for entities:

Even when retrieving a single entity, the resource name in the endpoint should be plural to denote the collection.

Example:

/api/v1/namespaces/{namespace}/pods          # collection of pods
/api/v1/namespaces/{namespace}/pods/{pod_id}  # single pod

Using the plural form consistently improves readability, makes endpoints predictable, and clearly distinguishes between collections and individual entities.

Limit relationship depth to two entities:

When representing relationships between entities in the endpoint, it is recommended to limit the path to two entities (e.g., /api/v1/customers/{customer_id}/employees). Going beyond this introduces unnecessary complexity and can lead to performance issues, as deeper relationships make the endpoint more difficult to manage and can impact scalability. Keeping the representation simple ensures better performance and maintainability.

2. Operation

The operation specifies the action to be performed on the resource. This is determined by the HTTP method used in the request. The most common HTTP methods include:

Idempotent by spec reflects what the HTTP specification (RFC 9110) mandates for the method. Idempotent by design marks methods that are not idempotent by spec but can be made so through deliberate implementation choices:

• POST — A payment system must not charge a customer twice on retried requests. This is solved with an Idempotency-Key header: the server stores the result of the first call and returns it unchanged on subsequent calls with the same key.
• PATCH — A partial update that sets an absolute value (e.g., {"status": "active"}) is idempotent; one that applies a relative delta (e.g., {"counter": "+1"}) is not.
• DELETE — A soft delete (setting a deleted_at timestamp or a status=deleted flag) makes the operation idempotent: a second call finds the resource already marked as deleted and returns the same successful response.

Some actions, like restarting a Pod, are not CRUD operations but can be modeled using POST, as they trigger an action on a resource without modifying it directly.

3. Parameters

Parameters define the information needed to execute the operation. There are three types of parameters that can be used:

• URL Parameters: These are part of the endpoint and are typically used to specify the resource’s identity, such as a specific resource ID (e.g., /pods/{pod_id}).
• Query Parameters: These are appended to the URL to refine or filter the results. They can specify things like pagination, sorting, or specific filters (e.g., ?limit=10 or ?status=active).
• Body Parameters: These are included in the body of the request and are typically used with methods like POST, PUT, and PATCH. Body parameters allow you to send complex data structures like JSON or XML to define the resource’s state or request changes.

4. Status Code

The status code is the HTTP response code that indicates the result of the operation. Common status codes include:

• 200 OK: The request was successful (used for GET, PUT, DELETE).
• 201 Created: The resource was successfully created (used for POST).
• 400 Bad Request: The request was malformed or invalid.
• 404 Not Found: The resource was not found.
• 405 Method Not Allowed: The requested method (i.e. GET, POST, etc.) has not been implemented for the specified resource.
• 409 Conflict: Conflicting state or rate limit reached.
• 500 Internal Server Error: There was an error on the server side.
• 503 Bad Gateway / Service Unavailable: Usually when a 3rd party subsystem is unavailable.

5. Response

The response is the data returned from the server after processing the request. This can include:

• A representation of the resource (for GET requests).
• A confirmation message (for POST, PUT, or DELETE requests, indicating success or failure).
• A failure message (for errors, explaining what went wrong).

The response should be formatted in a structured and predictable way (typically JSON or XML) so that the client can easily parse and understand the result.

These components — endpoint, operation, parameters, status code, and response — form the backbone of any API rule. By clearly defining these elements, you ensure that the API is intuitive, consistent, and easy to use for clients. These rules are the foundation that will guide how entities interact with each other in a system, ensuring that the API remains predictable, maintainable, and aligned with business needs.

Managing a Pod via API

Since it’s impossible in an article cover the API for all the above mentioned resources, let’s see how to define the API for the Pod resource.

In Kubernetes, these are the typical operations you can perform on a Pod, including both CRUD operations and a non-CRUD action like restarting a Pod.

Managing Pod via API

1. CREATE (POST)

• Endpoint: /api/v1/namespaces/{namespace}/pods
• Operation: POST
• Parameters: Body (JSON representation of the Pod specification, equivalent to what would be defined in a YAML file)
• Description: Create a new Pod in the specified namespace. The JSON body contains the Pod definition, including metadata and specification (containers, images, etc.).
• Status Code: 201 Created
• Response: Details of the created Pod.

2. READ (GET)

• Endpoint: /api/v1/namespaces/{namespace}/pods (to list all Pods in a namespace) or /api/v1/namespaces/{namespace}/pods/{pod_id} (to retrieve a specific Pod)
• Operation: GET
• Parameters: URL parameters (namespace, pod_id), Query parameters (e.g., ?status=running)
• Description: Retrieve information about a specific Pod or a list of Pods.
• Status Code: 200 OK
• Response: The Pod’s details (e.g., metadata, status, containers).

3. UPDATE (PUT)

• Endpoint: /api/v1/namespaces/{namespace}/pods/{pod_id}
• Operation: PUT
• Parameters: Body (Updated Pod specification in JSON)
• Description: Replace an existing Pod’s specification with a new one (e.g., updating resources).
• Status Code: 200 OK
• Response: The updated Pod details.

4. PARTIAL UPDATE (PATCH)

• Endpoint: /api/v1/namespaces/{namespace}/pods/{pod_id}
• Operation: PATCH
• Parameters: Body (Partial update, e.g., only changing the labels or annotations).
• Description: Apply partial updates to a Pod’s specification, such as modifying labels, annotations, or other attributes without replacing the entire Pod.
• Status Code: 200 OK
• Response: The updated Pod details.

5. DELETE (DELETE)

• Endpoint: /api/v1/namespaces/{namespace}/pods/{pod_id}
• Operation: DELETE
• Parameters: URL parameters (namespace, pod_id)
• Description: Delete the specified Pod.
• Status Code: 200 OK, 202 Accepted if the deletion is asynchronous, or 204 No Content if the operation is successfully but there is no content in the response.
• Response: Confirmation of deletion.

Authentication and Authorization in APIs (Kubernetes as a Case Study)

In any API, authentication and authorization are critical to ensure that only legitimate users can perform allowed operations on the system’s resources. Conceptually, these principles apply to all APIs, not just Kubernetes.

Authentication and Authorization

1. Authentication

• Authentication verifies the identity of a user or client.
• Typically, a user presents a credential, such as a client ID and secret, a JWT token, or a certificate.
• The application validates the credential and extracts the user identity.

Principle: If the identity cannot be verified, the API must return HTTP 401 Unauthorized.

2. Authorization

• Authorization determines what the authenticated user can do.
• Once a user is identified, the system maps the user to roles, and roles define permissions on resources.
• Each role can be scoped to a part of the system (i.e. in Kubernetes Namespaced resources or Cluster-scoped resources).

Principle: If the user is authenticated but lacks permission for an operation, the API must return HTTP 403 Forbidden.

3. Role Mapping and Bindings (Case Study: Kubernetes)

When you design your application you need to:

• Define a set of roles;
• Define a scope for each role;
• Define the operations the role can do in that scope.

Kubernetes illustrates these concepts:

• A Role defines operations allowed on namespaced resources (e.g., Pods, Services).
• A ClusterRole defines operations allowed on cluster-scoped resources (e.g., Nodes, PersistentVolumes).
• Users are associated to roles via:
  • RoleBinding → links user to a Role in a namespace
  • ClusterRoleBinding → links user to a ClusterRole cluster-wide

This design allows a many-to-many mapping: users can have multiple roles, and roles can apply to multiple users.

4. Context of Operation

When a user interacts with the API, the system maintains a context that encapsulates all relevant information:

• User identity — who is making the request
• Roles — the permissions assigned to this user
• Scope — the resource context (namespaced or cluster-scoped) where operations are allowed

This context is used by the application to enforce authorization rules consistently for each request.

5. Key Takeaways for API Design

• Authentication and authorization should be explicit and predictable: unauthorized requests → 401, forbidden operations → 403.
• Roles should be mapped clearly to resources, respecting their scope.
• Maintaining a user context makes it easier to check permissions and enforce rules consistently.

Kubernetes demonstrates this clean separation of identity (authentication), capability (authorization), and scope (context), providing a model that can be applied to any API design.

Error Handling in APIs

One of the key differences between a professional API and one created by inexperienced developers is how errors are handled. Proper error handling ensures that clients can reliably understand what went wrong and respond appropriately.

While frameworks like FastAPI (Python) or Spring Boot (Java) provide built-in mechanisms for error handling, the principles are framework-agnostic.

API Error Handling

1. Resource Not Found (404)

• When performing operations like GET, PUT, PATCH, DELETE on a resource identified by an ID, if the resource does not exist, the API must return 404 Not Found.
• Returning 200 OK with a message like “resource not found” is incorrect, because clients rely on the HTTP status code to handle errors programmatically.

Example:

GET /api/v1/namespaces/default/pods/nonexistent
Response: 404 Not Found

2. Validation Errors (400, 422)

If the client sends invalid input, such as:

• Missing required fields
• Incorrect data types
• Malformed JSON

the API should return 400 Bad Request or 422 Unprocessable Entity.

Frameworks like FastAPI + Pydantic or Spring Boot with validation annotations make it easy to automatically validate input and return the appropriate status code.

3. Authentication and Authorization Errors (401, 403)

• 401 Unauthorized: The client’s identity could not be verified (e.g., missing or invalid token).
• 403 Forbidden: The client is authenticated but does not have permission to perform the requested operation.

These errors were covered in the Authentication and Authorization section, but they are a crucial part of robust error handling.

4. Method Not Allowed (405)

405 Method Not Allowed is returned when the client attempts to use an HTTP method that is not supported for a given resource.

Example:

POST /api/v1/customers/{id}
Response: 405 Method Not Allowed

This error is typically implemented automatically by the framework (e.g., FastAPI or Spring Boot), based on how routes and HTTP methods are defined. The application logic should not manually handle this case.

5. Rate Limiting (429)

429 Too Many Requests indicates that the client has exceeded the allowed request rate.

This error is:

• Typically enforced at the API gateway or infrastructure level
• Not implemented inside the application code

Common use cases include:

• Abuse prevention
• Traffic control
• Fair usage policies

The response often includes headers such as Retry-After to indicate when the client can retry.

6. Server Errors (500, 503)

• 500 Internal Server Error: Indicates unexpected failures, such as programming errors or unhandled exceptions.
• 503 Service Unavailable: Indicates that a dependency is temporarily unavailable, for example when the API cannot reach the database or an external service is down.

These codes allow clients to distinguish between a system failure and a temporary unavailability.

API Documentation

APIs should be self-describing, meaning that each endpoint should be clear and understandable without requiring external documentation. However, tools like Swagger have greatly simplified the publication and management of API documentation. Frameworks such as FastAPI allow you to automatically generate Swagger documentation for every API, making it interactive and easily accessible.

API Documentation with Swagger

When using Swagger, it’s a best practice to group APIs by the entities they belong to. In FastAPI, this can be achieved using tags. For example, all APIs related to a specific entity, such as Customer, can be grouped under the Customer tag. This approach helps to keep the documentation clear and well-structured, with each group of APIs representing the “rules” for that particular entity.

For every API, it’s essential to properly document the following details in the code:

• Summary: A brief description of what the API does, allowing users to quickly understand its purpose.
• Description: A more detailed explanation of the API, providing additional context on its behavior.
• Parameters: A list of all the parameters the API accepts, along with information about their type and whether they are required.
• Error Codes: A list of possible error codes the API may return, along with brief explanations of what each code means.

These details will automatically be included in the Swagger documentation, making it comprehensive and easy to navigate.

Moreover, Swagger also acts as a client, allowing developers to directly test the APIs from the documentation interface, which simplifies testing and debugging during development.

Conclusion

In this article we covered:

• Entity modeling from requirements: How Clean Architecture principles and user stories identify domain entities and their boundaries prior to writing any API code.
• Resource mappings and relationships: Structuring RESTful endpoints with plural naming conventions and shallow nesting hierarchies (maximum 2 entities).
• HTTP semantics and operations: Mapping CRUD and action-based workflows to standard HTTP methods (GET, POST, PUT, PATCH, DELETE) with predictable status codes.
• Authentication, authorization, and context: Enforcing access controls via roles, scopes, and execution contexts, using Kubernetes RBAC (Role, ClusterRole, RoleBinding) as an architectural blueprint.
• Standardized error handling and Swagger documentation: Returning machine-readable status codes and using tags and OpenAPI metadata to generate self-documenting APIs.

The next article will put these architectural principles into practice: building a production-ready asynchronous REST API using FastAPI, with thread pools for blocking operations and dependency injection patterns.

Introduction

The previous article covered the theory: the GIL, thread pools, process pools, and why the event loop beats them all for I/O-bound concurrency at scale. Theory is useful until you sit down to write something real.

This article builds a concrete project from scratch — an async news aggregator that fetches RSS feeds concurrently and formats a digest ready to send via WhatsApp. The code is the same used in the open-source Alfred project: it starts minimal and grows with one new pattern per section: gather, TaskGroup, asyncio.timeout, Semaphore, and format_news. By the end you have a working, production-grade async application and a clear mental model of when and why to reach for each tool.

You should read this article if:

• You understand the theory of asyncio but have not yet built something real with it.
• You want to see TaskGroup, Semaphore, and asyncio.timeout used together in a single project rather than in isolation.
• You are comfortable with Python but new to aiohttp and concurrent I/O patterns.

This article is part of the Modern Python Application series.

The Project: An Async News Aggregator

The aggregator in this article is based on the news.py module from the open-source Alfred project — a personal assistant that fetches daily news and delivers it via WhatsApp. The article walks through the same patterns the real module uses, introducing them one step at a time. The final section points out where the production code goes further.

The aggregator fetches headlines from five RSS sources — the same default feeds configured in Alfred:

The final output is a formatted text digest ready to be sent via WhatsApp, with each item showing title and a short summary stripped of HTML.

Install the dependencies first:

pip install aiohttp feedparser

• aiohttp — async HTTP client; see the aiohttp documentation for the full API reference
• feedparser — synchronous RSS/Atom/RDF parser; we feed it raw XML already in memory; see the feedparser documentation for the full entry field reference

Step 1 — One Feed, One Coroutine

Start with the simplest possible version: fetch a single RSS feed and parse it. The real Alfred module also strips HTML from each entry’s summary — let’s include that from the start, since it is a two-liner and avoids HTML noise in the output.

# news.py
import asyncio
import re

import aiohttp
import feedparser

TIMEOUT = aiohttp.ClientTimeout(total=10)
HEADERS = {"User-Agent": "Mozilla/5.0 (compatible; AlfredBot/1.0)"}
MAX_SUMMARY = 150


def _strip_html(text: str) -> str:
    """Remove HTML tags, collapse whitespace, and truncate to MAX_SUMMARY chars."""
    clean = re.sub(r"\s+", " ", re.sub(r"<[^>]+>", "", text)).strip()
    return clean[:MAX_SUMMARY] + "…" if len(clean) > MAX_SUMMARY else clean


async def fetch(session: aiohttp.ClientSession, url: str, limit: int = 3) -> list[dict]:
    async with session.get(url) as resp:
        resp.raise_for_status()
        text = await resp.text()
    feed = feedparser.parse(text)
    return [
        {
            "title": e.get("title", "").strip(),
            "link": e.get("link", ""),
            "summary": _strip_html(e.get("summary", "")),
        }
        for e in feed.entries[:limit]
    ]

async def main() -> None:
    async with aiohttp.ClientSession(timeout=TIMEOUT, headers=HEADERS) as session:
        items = await fetch(session, "https://feeds.bbci.co.uk/news/world/rss.xml")
    for item in items:
        print(item["title"])
        print(item["summary"])

asyncio.run(main())

A few things worth noting:

• HEADERS sets a User-Agent string. Many RSS servers silently return 403 for requests that look like bots without a recognisable user agent — this one-liner prevents that class of failure entirely.
• aiohttp.ClientSession is created once and reused for all requests. Creating a session per request is the most common aiohttp mistake — it bypasses connection pooling entirely. One session per application is the rule.
• ClientTimeout(total=10) sets a 10-second cap on the full operation. Without a timeout, a hanging feed hangs your entire program indefinitely.
• feedparser.parse(text) is synchronous but runs in microseconds once the XML is already in memory — no need to offload it to a thread.
• resp.raise_for_status() raises aiohttp.ClientResponseError for any 4xx or 5xx response immediately, rather than letting malformed data propagate silently.
• _strip_html() removes HTML tags from the summary using two regex passes: first strips tags, then collapses whitespace. The truncation at MAX_SUMMARY chars keeps WhatsApp messages readable.

A coroutine object does nothing until it is awaited. fetch(session, url) returns a coroutine — the HTTP request only fires when the event loop reaches await.

Step 2 — Multiple Feeds with asyncio.gather

Fetching feeds one by one defeats the purpose of async. asyncio.gather runs multiple coroutines concurrently — all five requests are in-flight simultaneously, and the total wall time equals the slowest single response, not the sum.

DEFAULT_FEEDS = {
    "BBC News":      "https://feeds.bbci.co.uk/news/world/rss.xml",
    "Repubblica":    "https://www.repubblica.it/rss/homepage/rss2.0.xml",
    "Wired":         "https://www.wired.com/feed/rss",
    "Sky Sport":     "https://sport.sky.it/rss/sport.xml",
    "Science Daily": "https://www.sciencedaily.com/rss/top/science.xml",
}

async def main() -> None:
    async with aiohttp.ClientSession(timeout=TIMEOUT, headers=HEADERS) as session:
        results = await asyncio.gather(
            *[fetch(session, url) for url in DEFAULT_FEEDS.values()],
            return_exceptions=True,
        )
    for source, result in zip(DEFAULT_FEEDS.keys(), results):
        if isinstance(result, Exception):
            print(f"{source}: error — {result}")
        else:
            for item in result:
                print(f"[{source}] {item['title']}")

return_exceptions=True is the key choice here. Without it, the first failed feed raises immediately and you lose all results. With it, exceptions are returned as values alongside successful results — you check isinstance(result, Exception) and continue. This is the right default for an aggregator where partial results are genuinely useful.

The limitation: if one feed fails, the others keep running regardless. There is no automatic cancellation. That is sometimes what you want (independent sources) and sometimes not (a batch of dependent requests where partial data is useless). The next section shows the alternative.

Step 3 — Structured Concurrency with TaskGroup

asyncio.TaskGroup (Python 3.11+, see the official docs) enforces a stricter contract: if any task raises an unhandled exception, all siblings are cancelled and an ExceptionGroup is raised at the async with exit. Think of it as gather with a safety net (here, that safety net never triggers — fetch_safe absorbs every exception internally before TaskGroup can see it).

For the aggregator, feeds are independent sources — a failure in one should not kill the others. The right pattern here is to absorb errors inside fetch_safe and return them as a third tuple element, then let TaskGroup manage the concurrency cleanly:

async def fetch_safe(
    session: aiohttp.ClientSession,
    source: str,
    url: str,
    limit: int = 3,
) -> tuple[str, list[dict], Exception | None]:
    try:
        items = await fetch(session, url, limit=limit)
        return source, items, None
    except Exception as exc:
        return source, [], exc

async def main() -> None:
    results: dict[str, list[dict]] = {}
    failed: dict[str, Exception] = {}

    async with aiohttp.ClientSession(timeout=TIMEOUT, headers=HEADERS) as session:
        async with asyncio.TaskGroup() as tg:
            tasks = {
                source: tg.create_task(fetch_safe(session, source, url))
                for source, url in DEFAULT_FEEDS.items()
            }

    for source, task in tasks.items():
        _, items, error = task.result()
        if error is not None:
            failed[source] = error
        else:
            results[source] = items

tg.create_task() schedules each coroutine as a Task immediately. The async with block does not exit until all tasks are complete — no manual await for each one. The tasks dictionary gives you named access to each result after the group closes.

Notice that fetch_safe now returns a 3-tuple (source, items, error | None) instead of mixing exceptions and data in a single list. The error travels alongside the result as a first-class field — the caller unpacks it cleanly with _, items, error = task.result() and routes failures to a separate failed dict without any isinstance check.

Use TaskGroup when you want structured lifetimes for a set of concurrent tasks. Use gather(return_exceptions=True) when you need to collect all results including errors as data.

As Hynek Schlawack notes, TaskGroup is now the recommended default for scheduling a nested group of tasks — it has fewer sharp edges than gather and its cancellation semantics are unambiguous.

Step 4 — Per-Request Timeouts with asyncio.timeout

The global ClientTimeout covers the session default, but individual feeds can be slower or faster. asyncio.timeout (Python 3.11+) wraps any block of async code with a deadline — if the block takes longer than n seconds, it raises TimeoutError and cancels the inner task cleanly.

async def fetch_safe(
    session: aiohttp.ClientSession,
    source: str,
    url: str,
    timeout: float = 8.0,
    limit: int = 3,
) -> tuple[str, list[dict], Exception | None]:
    try:
        async with asyncio.timeout(timeout):
            items = await fetch(session, url, limit=limit)
        return source, items, None
    except TimeoutError as exc:
        return source, [], exc
    except Exception as exc:
        return source, [], exc

asyncio.timeout is more composable than asyncio.wait_for — it is an async context manager that wraps a block rather than a single coroutine call. This means you can cover multiple await expressions with a single deadline, which is useful when a feed requires a follow-up request to resolve redirects.

One important rule: TimeoutError must be caught outside the async with asyncio.timeout(...) block, not inside it. The context manager converts the internal CancelledError into TimeoutError at its exit — catching it inside would swallow it before the conversion.

Step 5 — Rate Limiting with asyncio.Semaphore

Five feeds is manageable, but extend this to 50 sources and you risk triggering rate limits or overwhelming slow servers with a burst of simultaneous connections. asyncio.Semaphore is a counter that limits how many coroutines can be inside a critical section at the same time.

async def fetch_safe(
    session: aiohttp.ClientSession,
    source: str,
    url: str,
    semaphore: asyncio.Semaphore,
    timeout: float = 8.0,
    limit: int = 3,
) -> tuple[str, list[dict], Exception | None]:
    async with semaphore:  # acquire slot; blocks if all slots are taken
        try:
            async with asyncio.timeout(timeout):
                items = await fetch(session, url, limit=limit)
            return source, items, None
        except TimeoutError as exc:
            return source, [], exc
        except Exception as exc:
            return source, [], exc


async def _fetch_all(
    feeds: dict[str, str], limit: int = 3
) -> tuple[dict[str, list[dict]], dict[str, Exception]]:
    semaphore = asyncio.Semaphore(3)
    results: dict[str, list[dict]] = {}
    failed: dict[str, Exception] = {}

    async with (
        aiohttp.ClientSession(timeout=TIMEOUT, headers=HEADERS) as session,
        asyncio.TaskGroup() as tg,
    ):
        tasks = {
            source: tg.create_task(fetch_safe(session, source, url, semaphore, limit=limit))
            for source, url in feeds.items()
        }

    for source, task in tasks.items():
        _, items, error = task.result()
        if error is not None:
            failed[source] = error
        else:
            results[source] = items

    return results, failed