Not because I don’t know what it does or how to use it, that part’s fine. I write my async defs, slap some await in there, and it just works™️. No, what's bothering me is: why does it work?

If we’re not blocking the main process... who’s doing the actual work I’m awaiting? And more importantly, how does the result get back into my Python function?

Take a typical FastAPI route. Maybe we’re calling an external API:

import httpx
from fastapi import APIRouter

router = APIRouter()

@router.get("/user/{id}")
async def get_user(id: str):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{id}")
    return response.json()

The request comes in, the interpreter hits await client.get(...), and somehow... the server keeps handling other requests while the HTTP call is doing its thing.

Doing its thing where, exactly?

And once it's done, who taps the interpreter on the shoulder to say: "Hey, here’s your response. You can resume now." ?

It all feels a bit too magical, and I hate magic. That's why I always end up playing a sneaky archer in Skyrim.

This post is about removing the magic and understanding how it all works under the hood. We'll build our own version of asyncio step by step , from a simple generator all the way to running a fully working echo server using only our custom event loop.

Here is what the end result will look like :

from socket import SO_REUSEADDR, SOL_SOCKET, socket
from scheduler.future import AcceptSocket, ReadSocket, Sleep
from scheduler.scheduler import Scheduler


async def read(conn):
    return await ReadSocket(conn)


async def accept(sock):
    return await AcceptSocket(sock)


async def echo(sock):
    while True:
        data = await read(sock)
        if not data:
            sock.close()

        print(f"received {data}")
        # assume non-blocking
        sock.send(data)


async def echo_server(scheduler: Scheduler, port: int):
    print("creating socket...")
    sock = socket()
    sock.bind(("localhost", port))

    sock.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1)
    sock.listen(100)
    sock.setblocking(False)
    print("socket created waiting for connection")
    while True:
        conn = await accept(sock)
        # Schedule new concurrent connection
        scheduler.create_task(echo(conn))


if __name__ == "__main__":
    scheduler = Scheduler()
    scheduler.create_task(echo_server(scheduler, 1235))
    scheduler.run_forever()

To do that, we’ll need three things:

• A way to pause a function and resume where we left off.

• A way to switch between those paused/resumable functions.

• A way to start the work somewhere else, and get notified when it’s done.

Sound familiar? That first point should ring a bell: generators! Generators let us pause in the middle of a function and resume it later. And fun fact: that’s very close to how asyncio actually works under the hood.

(Want to skip ahead? Check out the full repo here with all the code we'll write in this post.)

Primer on Generators and Coroutines

First a small primer on generators, and their twin coroutines.

In python, generators are created (among other ways) using yield. A yield statement pauses the callee and returns something to the caller. This allows to do cool stuff like maintaining state across multiple function executions.

Here's an example generator that when iterated over return the Fibonacci sequence:

from time import sleep


def fibonnaci_generator():
    n_1 = 0
    n_2 = 1
    while True:
        n = n_1 + n_2
        yield n

        n_2 = n_1
        n_1 = n


if __name__ == "__main__":
    generator = fibonnaci_generator()
    for x in generator:
        print(x)
        sleep(1)

Calling fibonacci_generator() gives us a generator object. Iterating over it calls yield repeatedly, pausing and resuming the function between each number.

But yield has a hidden superpower: it doesn’t just let a generator produce values, it also allows it to receive values using my_generator.send(value). This turns the generator into a data consumer, not just a producer.

A generator that can receive data like this is often referred to as a coroutine. Why coroutine? Because unlike regular subroutines (which run top-to-bottom and return once) they can pause, yield control, and be resumed later with external data, possibly by some external scheduler. That makes them perfect for cooperative multitasking, where functions can run concurrently by explicitly handing control back and forth, and sending values to each other, rather than stacking up on the call stack like traditional functions.

⚠️ Quick note on terminology:

In this post, I’m using the term coroutine in its broader, general sense. In Python, this includes generator functions that use yield and .send() to cooperate with a scheduler.

These generator-based coroutines were the first way to write asynchronous code in Python. Since version 3.5, Python introduced native coroutines using the async def and await keywords. Native coroutines are more ergonomic, but conceptually, they do the same thing: pause, wait for something, then resume.

We’ll explore those native coroutines, and how our library supports them, later in the post.

send will come in handy when we want to send the result of an asynchronous operation back into the paused coroutine.

Let’s see this in action. We’ll write a coroutine that filters even numbers from the Fibonacci sequence (yes, it’s very useful):

from time import sleep


def fibonnaci_generator():
    n_1 = 0
    n_2 = 1
    while True:
        n = n_1 + n_2
        yield n
        sleep(1)

        n_2 = n_1
        n_1 = n


def filter_even():
    while True:
        x = yield
        if x > 200:
            return x
        if x % 2 == 0:
            print(x)


if __name__ == "__main__":
    filter = filter_even()
    generator = fibonnaci_generator()
    filter.send(None)
    for x in generator:
        filter.send(x)

Notice how filter_even consumes values generated by fibonnaci_generator ? That's the difference between generator and coroutines. Of course, a generator can do both, but that gets messy quickly, and I won’t get into why here. (You can find a good explanation p.16 of A Curious Course on Coroutines and Concurrency)

That's enough theory on coroutines for now. But look, we've already completed step 1: we now have a way to pause and resume execution. Next up: running coroutines concurrently with a scheduler.

Building a Scheduler

We'll build a Scheduler that well be responsible for, that's right, scheduling our coroutines. First, let's write a Task wrapper to encapsulate all the coroutine stuff:

from typing import Generator
import uuid


class Task:
    def __init__(self, coro: Generator):
        self.id = uuid.uuid4()
        self._coro = coro
        self.val = None

    def run(self):
        return self._coro.send(self.val)

the val attribute represents the next value we want to send to the coroutine. We’ll use it to give back some result to the wrapped coroutine later on. After initialization, it’s None. Sending None to a coroutine is equivalent to calling next on it, and will advance to the next yield statement.

Next, we write a simple scheduler to manage the tasks queue:

from collections import deque
from typing import Generator

from scheduler.task import Task


class Scheduler:
    def __init__(self):
        self._queue = deque([])

    def create_task(self, coro: Generator):
        task = Task(coro)
        self._queue.append(task)

    def run_forever(self):
        while self._queue:
            task = self._queue.pop()
            try:
                task.run()
                self._queue.appendleft(task)
            except StopIteration as err:
                print(err.value)

This is as simple while loop that take the next task in the queue and run it once. Then either:

• We reschedule the task at the back of the queue

• StopIteration is raised, meaning the coroutine is over, and the task isn't rescheduled

💡 StopIteration is raised when a generator (or generator-style coroutine) finishes execution.
This happens either:

• When it reaches the end of the function, or

• When it hits a return statement (in which case the return value is stored in the exception’s .value attribute)

Let's see this in action. We'll build two simple coroutines, ping and pong, that print their own name and yield. We can use your brand new Scheduler to run them.

import time

from scheduler.scheduler import Scheduler


def ping():
    while True:
        print("ping")
        time.sleep(1)
        (yield)


def pong():
    while True:
        print("pong")
        time.sleep(1)
        (yield)


if __name__ == "__main__":
    scheduler = Scheduler()
    scheduler.create_task(ping())
    scheduler.create_task(pong())
    scheduler.run_forever()

Great! As you can see, our scheduler alternates between the ping and pong tasks. That’s step 2 done.

However, for now, we still can’t really “await” anything. If we modify ping to use a blocking sleep(30), it will pause for 30 seconds before the scheduler can switch to pong.

Right now, our scheduler behaves similarly to running both tasks in separate threads, except we are the ones deciding when the switch happens. This model is called cooperative multitasking, but we are still missing our third ingredient: something to delegate the work and be notify when it's done.

This is where the Future class comes into play

Adding a Future

A Future is similar to a Promise in TypeScript. It represents a value that’s not available yet, but will be eventually. That’s exactly what we need: we want our coroutine to yield a Future, and then have our scheduler “pause” it until that future is resolved.

Here’s a base Future class we can work with:

class Future(TaskProtocol, metaclass=ABCMeta):
    def __init__(self):
        self._done_callbacks = []
        self.is_done = False
        self._result = None
        self._coro = self._run()

    def add_done_callback(self, callback: Callable[[Any], None]):
        self._done_callbacks.append(callback)

    def run(self):
        self._coro.send(None)

    def _run(self):
        while True:
            result = self._check_result()
            if result:
                self._done(result)
                return result
            yield

    def _done(self, result: Any):
        self.is_done = True
        self._result = result
        for callback in self._done_callbacks:
            callback(self._result)

    @abstractmethod
    def _check_result(self) -> Any:
        pass

A few things to notice here:

The Future has a run method, just like our Task. This is because the Future will replace the task in the queue, having a task-like interface allows us to treat it like a normal task.

💡 The TaskProtocol is define elsewhere, it simply enforces this shared interface between Future and Task

The Future wraps a coroutine in _run, which polls for the result. When it’s ready, we mark the future as done and trigger any callbacks waiting on it.

When a Task yields a Future, that future replaces the task in the queue, and holds a reference to the task. That’s how we “pause” the coroutine. Once the future is complete, it will call its registered callback to reschedule the waiting task with the result, resuming it. In our case, the scheduler will be responsible for setting this callback.

from collections import deque
from typing import Generator

from scheduler.future import Future
from scheduler.task import Task
from scheduler.task_protocol import TaskProtocol


class Scheduler:
    def __init__(self):
        self._queue = deque([])

    def create_task(self, coro: Generator):
        task = Task(coro)
        self._schedule(task)

    def _schedule(self, task: TaskProtocol):
        self._queue.appendleft(task)

    def _continue(self, task):
        def callback(result):
            task.val = result
            self._schedule(task)

        return callback

    def run_forever(self):
        while self._queue:
            task = self._queue.pop()
            try:
                future = task.run()
                if isinstance(future, Future):
                    future.add_done_callback(self._continue(task))
                    self._schedule(future)
                else:
                    self._schedule(task)
            except StopIteration:
                pass

Now when a task yields a Future, the scheduler sets a callback that:

• Assigns the result back to the task (task.val)

• Reschedules the task so it can resume execution

This is not very easy to visualize, so here is a sequence diagram showing what happens:

Let’s put this to the test. Here’s an implementation of a non-blocking sleep using this future logic:

class Sleep(Future):
    def __init__(self, wait_for: int, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._wait_for = timedelta(seconds=wait_for)
        self._ready_at = datetime.now(tz=timezone.utc) + self._wait_for

    def _check_result(self):
        if datetime.now(tz=timezone.utc) >= self._ready_at:
            return True

And now let's do some non-blocking awaiting:

import time

from scheduler.future import Sleep
from scheduler.scheduler import Scheduler


def sleep(n: int):
    return (yield Sleep(n))


def ping():
    print("waiting for result before ping...")
    result = yield from sleep(5)

    print(f"result: {result}")
    while True:
        print("ping")
        time.sleep(1)
        yield from sleep(0)


def pong():
    while True:
        print("pong")
        time.sleep(1)
        yield from sleep(0)


if __name__ == "__main__":
    scheduler = Scheduler()
    scheduler.create_task(ping())
    scheduler.create_task(pong())
    scheduler.run_forever()

We did it! ping pauses for 5 seconds, and during that time, pong can continue doing its thing. Just like with the real asyncio.sleep.

Also, note the use of yield from when nesting coroutines.If we had just done yield Sleep(n), we’d yield a generator instead of the result we wanted. If this seems too magical, check out the branch step/nested-coroutines in the linked repo. In that branch, I use stack in the Task class to handle nested co-routine manually.

Now we could stop here for our scheduler and skip to doing some I/O. But the real asyncio lib works with the async/await keywords. Wouldn’t it be nice if we could do that as well ?

Adhering to async/await

The keywords async and await don't introduce new features to Python's execution model. They simply organize and improve what we've been doing with yield from and generators.

There's no magic involved. await works like yield from, and async alters our function type from Generator to Coroutine. This helps keep asynchronous generators/coroutines separate from regular generators.

To convert our generator-based coroutines into true coroutines, we just need to add async before them. Then we can use await with them (which is a drop-in replacement for yield from).

To integrate our custom Future with Python's await system, we need to make it awaitable. This means implementing the __await__ method, which Python uses under the hood when you write await my_future.

class Future(TaskProtocol, metaclass=ABCMeta):
   def __init__(self):
       self._done_callbacks = []
       self.is_done = False
       self._result = None
       self._coro = self._run()

   def __await__(self):
       return (yield self)


    # ... rest of the class

And that's it, now we can change sleep like so

async def sleep(n: int):
    return await Sleep(n)

which is functionally the same as calling Sleep(n).__await__().

Let me say that again because it is important: async and await do no magic whatsoever. They are just part of a protocol, much like the Iterator protocol. Their purpose is to keep us from mixing up regular generators with coroutines that are meant to be managed by a scheduler or an event loop.

And now that our futures are awaitable, we can use async and await everywhere. In fact, we must use them, because once a function is declared with async def, the interpreter expects await inside, not yield.

from scheduler.future import Sleep
import time
from scheduler.scheduler import Scheduler


async def sleep(n: int):
    return await Sleep(n)


async def ping():
    print("waiting for result before ping...")
    result = await sleep(5)
    print(f"result: {result}")
    while True:
        print("ping")
        time.sleep(1)
        # yield control to the event loop. We cannot use (yield in a "true" coroutine)
        await sleep(0)


async def pong():
    while True:
        time.sleep(1)
        await sleep(0)
        print("pong")


if __name__ == "__main__":
    scheduler = Scheduler()
    scheduler.create_task(ping())
    scheduler.create_task(pong())
    scheduler.run_forever()

You can still use yield inside an async function in the context of Asynchronous Generators. But this is outside the scope of this post.

Look at that ! Pretty much exactly what this would look like using the regular asyncio, except it comes from our own library. Pretty neat, uh ?

Adding Real I/O to Our Async Framework

So far so good, but we still haven't handled any real I/O. What we have, though, is a framework that lets us build custom Future subclasses. Each of them can poll for a result and resume a task once that result is available.

At the beginning of the post, in the final code example, you may have noticed these two lines:

async def read(conn):
    return await ReadSocket(conn)

async def accept(sock):
    return await AcceptSocket(sock)

Well guess what? Both ReadSocket and AcceptSocket are subclasses of our Future class.

AcceptSocket allows us to suspend execution while waiting for new incoming connections on a socket. ReadSocket does the same for receiving data from a connection. Now that all the async plumbing is in place, their implementation is surprisingly simple:

import selectors
from socket import socket

class AcceptSocket(Future):
    def __init__(self, sock: socket, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._select = selectors.DefaultSelector()
        self._sock = sock
        self._select.register(sock, selectors.EVENT_READ)

    def _check_result(self):
        events = self._select.select(0)
        if events:
            conn, addr = self._sock.accept()
            print("accepted", conn, "from", addr)
            conn.setblocking(False)
            return conn

class ReadSocket(Future):
    def __init__(self, sock: socket, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._select = selectors.DefaultSelector()
        self._sock = sock
        self._select.register(sock, selectors.EVENT_READ)

    def _check_result(self):
        events = self._select.select(0)
        if events:
            return self._sock.recv(1000)

I won't go into the details of how sockets work in Python. If you need a refresher (I did!), the socket module docs are a great place to start.

The key thing here is the selectors module. It lets us monitor socket readiness without blocking the main thread. And that, finally, answers the question I posed at the beginning of this article:

"Who's doing the work while we await?"

The answer is simple. The operating system is. When we call register(), we ask the OS to monitor the socket for readiness. Each time we call select(0), we check for any ready events without blocking. This makes implementing the _check_result overrides a piece of cake. We simply check if something is ready in the socket, and if so we return it. If not, we’ll check again during the next loop iteration. Our scheduler handles resuming the appropriate task.

Now that everything is in place, we can finally build a working echo server:

from socket import SO_REUSEADDR, SOL_SOCKET, socket
from scheduler.future import AcceptSocket, ReadSocket, Sleep
from scheduler.scheduler import Scheduler


async def sleep(n: int):
    return await Sleep(n)


async def read(conn):
    return await ReadSocket(conn)


async def accept(sock):
    return await AcceptSocket(sock)


async def echo(sock):
    while True:
        data = await read(sock)
        if not data:
            sock.close()

        print(f"received {data}")
        # assume non-blocking
        sock.send(data)


async def echo_server(scheduler: Scheduler, port: int):
    print("creating socket...")
    sock = socket()
    sock.bind(("localhost", port))

    sock.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1)
    sock.listen(100)
    sock.setblocking(False)
    print("socket created waiting for connection")
    while True:
        conn = await accept(sock)
        # Schedule new concurrent connection
        scheduler.create_task(echo(conn))


if __name__ == "__main__":
    scheduler = Scheduler()
    scheduler.create_task(echo_server(scheduler, 1235))
    scheduler.run_forever()

The echo coroutine handles a single client connection. The echo_server coroutine waits for new clients and launches a new concurrent instance of echo for each one. You can run the script and connect multiple clients to port 1235 to see it in action. The echo_server is avaible in the scheduler package of the repository

🎉 Conclusion

If you've made it this far, congratulations! Our implementation is pretty close to the real thing, and asyncio should feel way less mysterious.

Of course, it gets more complex when you want to support timeouts, cancellation, priorities, etc., but the foundation remains the same. If you want to dig deeper, check out the asyncio source in the CPtyon repository, it should look pretty familiar now.

Turns out, the real magic isn’t the await. It's the yield we wrote along the way.

References

1. https://www.dabeaz.com/coroutines/

2. https://docs.python.org/3/library/asyncio-task.html

3. https://snarky.ca/how-the-heck-does-async-await-work-in-python-3-5/

There seemed to be some confusion surrounding the subject which isn't surprising. Indeed, while reverting a merge commit is definitely possible, it can have unintended consequences that are a pain to deal with. Specifically, once you’ve reverted the merge, re-introducing the changes from your PR is not straightforward. Having struggled with this a few times myself, I thought I’d do a small write-up to clear things up!

By the end of this post, you should know how to revert merge commits, and more importantly, how to re-introduce your changes once you’re done with your fix. This assumes basic knowledge of git.

Let’s dive in!

What’s in a merge commit

First things first, we need to clarify a few things about merge commits, this will be important later on. When you’re merging a branch, say a feature branch into master, git does basically 3 things :

• Determine the closest common ancestor of the two branches. This allows git to compute the diff between the two branches, and detect eventual conflicts.
• Create a commit containing the changes from both branches. This is the merge commit
• Add the last commits of the branches you’re merging as ancestors to the merge commit. This means every merge commit has two ancestors.

Once the merging is done, you’ll end up with something like this:

So far so good. But now let’s say you missed something. Something big. The buggy-feature branch above unexpectedly introduces a critical bug in production.

Ideally, you would be able to quickly narrow down the issue to one commit and deploy a hotfix to resolve the issue. However sometimes you simply cannot pinpoint which changes broke something, and you can’t afford to let the bug sit in production much longer.

In this sort of situation, you might want to revert the merge and sort out the rest later. Let’s see how to do that!

Reverting the merge commit

First of all, you can definitely revert a merge commit. It just works a bit differently than a regular commit. Indeed, if you try to revert it using git revert 181c8d1 you’ll be greeted by the following error message:

The revert failed, and what’s this “-m option” stuff about?

Well, remember, merge commits have two ancestors. Thus, git must know which ancestor it should use as a reference to compute the diffs you want to remove. The content of the revert commit will differ depending on which ancestor you’re reverting to. And that’s what the -m option is for. Let’s see how it works.

The -m option takes the index of the ancestor you want to use as a reference. It can be either 1 or 2. Most of the time, if you’re reverting a merge commit from a PR into main, you want to revert to the previous main commit which means you’ll want -m 1.

If you want to be sure tho, just use git show on the merge commit:

Notice the “Merge:” line. It indicates both ancestors. When you pass -m 1 or -m 2 to the revert command, it tells git to use the first or second ancestor as listed on this line.

Now you’ve reverted the merge, and production is working again. You can breathe. Seriously just take the time to breathe, it does wonder for your health. Not breathing is strongly discouraged by most medical practitioners.

This is not over though. Once you’ve determined what’s wrong with your branch, you’ll probably want to add a commit to fix it and re-merge it into the master. And this is where things start to get hairy.

Re-introducing the feature after the fix

Why re-merging doesn’t work

Now with production up, you had time to figure out what's wrong with your branch. You’ve added a commit to fix that, and you’re ready to re-merge the branch. If you do so, you should end up with the following git history :

This looks fine at first, but you’ll probably quickly notice something is wrong again and might even create a new bug. Why is that? Well if you inspect the content of the master branch, you’ll discover that the content of the commits prior to the fix, Good Commit #1 and Buggy Commit #1 is missing. This is probably not what you want.

To understand why the commits are missing, we need to discuss what git does when you revert a merge commit :

• First, it looks at the difference between the merge commit and the ancestor you provide using the -m option
• then, it inverts the diff and commits the result. This is the “revert” commit.

What it doesn’t do, however, is delete the meta-data that indicates that the feature branch has already been merged. In the example above, this means, that Buggy commit is still an ancestor of the first merge commits. Which means that when you re-merge your branch, the following things happen:

• Git determines the closest common ancestor. Since the first merge is still in history, the closest common ancestor here is Buggy Commit.
• Git determines the difference. In this case, it creates a diff between the Revert commit and Buggy Commit.
• Git creates the merge commits, with two ancestors.

Good Commit #1 (and Buggy Commit #1) are part of the master branch history now. They cannot be included again.

What can you do then? Well, the git documentation isn’t really optimistic about the subject …

Reverting a merge commit declares that you will never want the tree changes brought in by the merge

… but there are solutions! Let’s look at a few of them!

How to “re-merge” your PR

Re-merging directly doesn’t do the trick, so we’ll have to be clever to force git to accept the changes from the branch. To do so they are a few alternatives

Reverting the revert

This is the most straightforward way to do it. To make your changes part of the master again, you can simply revert the revert commit. This will make it so the initial revert never happened, with both reverts canceling each other out. This might sound a bit confusing, so here’s what it looks like with our example :

Once you’ve done that you can simply merge the fix you’ve made to your PR and be done

Be careful tho, between the instant you revert the revert and the moment you merge the fix, the bug will be re-introduced. So if you’re using some kind of automation to auto-deploy pushes made to the main branch, be sure to perform this operation, before deploying. Otherwise, you risk re-deploying the bug.

This method is described in more detail in the official git how-to. (The not-so-obvious location of this doc might explain some of the confusion around this subject)

Cherry-Picking and Rebasing

Another alternative is starting a new branch from the main, and cherry pick the commit from your previous branch, including the fix. This will change the hash of the commit, so it won’t detect them in the branch history. (This also works using rebase --on-to , but not rebase alone as it will automatically use the closes common ancestor, which again will by “Buggy Commit #1”). If all goes well you should end up with something like this.

The commits from “buggy-feature” are duplicated with a different hash and can be “re-merged” into master.

Conclusion

Hope this clears things up! I think the main thing to take away here is that reverting a merge commit is very painful. Even tho they are alternatives, you might still end up with a lot of conflict resolution, especially if other people are working on the same repo. You could always ask your coworkers to stop working for a bit while you’re sorting this out, but this isn’t ideal either, especially on a big project.

What should you do then? Well, Linus explains it best:

If you find a problem that got merged into the main tree, rather than revert the merge, try really hard to bisect the problem down into the branch you merged, and just fix it, or try to revert the individual commit that caused it.

Authentication is something most web applications need, and that can be difficult to get right. Recently I had to implement it for a React app I was developing, and wanted to list the options available to me. So I did a bit of research and, to my surprise, I found it's really hard to get a straightforward answer on the proper way to implement authentication between an SPA and an API backend.

Since I had to do quite a bit of work to identify the distinct patterns I could choose from, I decided to compile them into an article so others could benefit from them! My goal here is to provide you with a good starting point should you ever want your user to be able to authenticate with your SPA.

Setting the context

Before diving deeper into the subject, it's important to have an idea of what we're trying to achieve and what we'd like to avoid. So let's review what we mean by "Authentication", and the main kind of security issues we need to look out for. However, if you'd like to skip all that and go straight to the authentication patterns, feel free to do so !

The three aspects of "Authentication"

Usually when we talk about implementing some kind of Authentication system on an application, we're actually talking about 3 different concepts. In a monolithic app, these are rarely explicitly stated, because they're usually tackled at the same time. However, as we'll see a bit later, some of the Authentication patterns available to SPA don't cover all of them, which means it's important to define them. These concepts are Authorization, Authentication and Session:

• Authorization: Determining if an entity is allowed to perform a specific action. This doesn't necessarily mean we need to know who is performing the action.
• Actual Authentication: Knowing the identity of the user. For example their email address, username or any property that can be used to uniquely identify a user in your domain of work.
• Session: Maintaining state for one or both of the above concepts

Keep that in mind, we'll refer to these definitions often throughout the article!

2 types of attack to avoid

Now that we know what we want, let's review what we don't want. That is, security flaws that could allow an attacker to by pass our authentication system. There are an infinite possibilities when it comes to attacking an application, and no system can claim to be completely secure. However, when building an authentication system, here are the ones we mainly need to worry about:

• Cross Site Request Forgery (CSRF);
• and, Cross Site Scripting (XSS, I guess CSS was already taken)

I'll quickly go over them, just so we can understand the mechanism we need to have in place to cover for these!

CSRF Attacks

These kind of attacks target authentication schemes that relies on cookies for storing credentials or session ID. They work by exploiting the fact that cookies related to a domain are automatically sent by the browser for every request made to the domain. This allows malicious website to set up forms designed to hit your application, and perform unwanted side-effects if your user is currently logged in.

There is also another kind of "reverse" CSRF attack which specifically targets login form. In these kind of attacks, the malicious website logs in the browser with the attacker account. Then when the user goes back to your app, thinking they're logged in with their own account, the attacker can gain access to any sensitive data they enter.

It's important to note that CORS settings alone do not prevent CSRF attacks. Indeed, with the exception of pre-flighted requests, CORS doesn't prevent the browser from making the request, it just prevents the response to be read by javascript.^[1]

XSS Attacks

A Cross-Site Scripting Attack is a really wide category of attacks, where a malicious person manage to inject some foreign javascript into your application. For example if you render some text coming from user input, without escaping potential HTML code, someone could pretty much do whatever they want with your SPA. Specifically regarding authentication, they could read any sensitive information stored in LocalStorage or SessionStorage, which is why you'll often read that you MUST not store session data into LocalStorage.^[2]

As a side note, some argue that this is a non subject as if you're vulnerable to XSS attacks, you have bigger issues to deal with anyway. For example an attacker could simply modify a login form to send credentials directly to their own server. Personally I disagree entirely as I think security measures should be self-contained and make no assumptions on the scale of the attack.

Authenticating with a monolith

One more thing : Before diving into the SPA world, I'd like to quickly review how it's done with a monolith. This way we'll have a reference point when talking about the specificities of SPA authentication.

With a monolith, usually it works like this:

Wait, not that kind of monolith

I mean like this:

Monolothic auth sequence diagram

It's simple really: once the user submits their credentials, the server creates a stateful session. Then it mints an httpOnly cookie containing a session id, which will be sent with each subsequent request. Authentication is performed by storing an identifier in the session, and Authorization is checked by looking up the rigths/roles/permissions/whatever associated with the identity. The session is maintained natively by the browser and the cookie.

A word on CSRF

As outlined in the previous section, using a cookie makes the app vulnerable to CSRF attacks. Most frameworks have a built in way to deal with it using a CSRF token mechanism similar to the one I've included into the sequence diagram. This is good, because building a CSRF token system is hard to do and easy to get wrong.

Authenticating with an SPA

All right, now that's out of the way, let's start with today's main subject. I'm sure you're glad you've just read 800 hundred words not related in any way to SPAs, in an article about SPAs. But this was necessary, and now we'got all the context we need to review the available SPA authentication patterns in a constructive way!

Option 1: Stateful session with cookie

This is the simplest approach, and closely resembles the monolithical one. Here's how it looks :

As with the monolithic architecture, the API creates a stateful session, and a Session Cookie 🍪, with the session ID. The only difference is that the UI is now provided by the SPA. It is a big difference though because:

• The SPA is Authorized to perform some actions on behalf of the user, but the user is only Authenticated with the API. Meaning the SPA doesn't know the identity of the user. If you choose this pattern you'll have to create a dedicated route (something like /me or /profile) to fetch the identity of the user.
• As we're now dealing with two different apps, for this approach to work you need to be able to share the cookie between them. This means they have to be hosted on the same domain

• Since we're using a cookie, we're vulnerable to CSRF attack. However contrary to the monolothic approach where it's often handled by the framework, you have to deal with it yourself.

  Dealing with CSRF attacks

In this case there are two main ways to prevent CSRF attacks:

• Setting SameSite on the cookie: This prevents the browser from automatically sending it along with requests made from another domain. This is the recommended approach by the OAuth2 specs on browser-based application^[3]. The only caveats is that this setting is only supported by recent browser versions, so users using outdated ones will be vulnerable!^[4]
• Manually setting up a CSRF mitigation method like a CSRF token. This can definetly work as outlined in this article but it's really easy to get wrong, so I'd use this option as a last resort.

Pros & Cons

Pros

• Low cost of implementation

Cons

• Older browser are not protected by SameSite cookie, you need to manually implement CSRF
• You must be able to share a domain with the server
• Doesn't provide direct authentication for the SPA, you need to make another call to a dedicated API route.

Option 2: Stateless JWT authentication

This pattern uses JWT to exchange authentication data. JWT is a standard for exchanging signed JSON data (signed, not secret !). If you want more details about how JWT work, Auth0 has a dedicated website with all the information you'll need. Here it's used to provide a stateless way to manage authentication in the SPA and authorization in the API:

Pretty straightforward, the credentials are exchanged against a JWT that contains :

• An Access Token used as a bearer token for authorization
• A Refresh Token for when the Access Token expires
• The identity of the user (often under the "sub" key of the json data)

This kind of authentication isn't as exposed to CSRF attacks if you don't store the JWT inside a cookie.

What about session

Maintaining session is problematic in this case. As explained earlier, we can't just store the Refresh Token inside the local storage, as it's vulnerable to XSS attacks. You could store it inside an HttpOnly cookie, but you lose the ability to authenticate the user with the JWT in the SPA. In that case I'd recommend using option 1 instead if possible, as it is more battle tested and easier to implement.

There is a way to give the illusion of maintaining an active session, but it requires a more complex approach, that is outlined in the next section.

Pros & Cons

Pros

• Provide both Authorization and Authentication of the SPA
• Stateless which may improve performance depending on your architecture. For example by saving a database lookup.

Cons

• Can't really maintain session in a secure way

Option 3: OpenID connect

OpenId Connect is an extension of the OAuth2 authorization framework that adds authentication capabilities to it.

OAuth2 was originally meant to allow a third-party app to perform actions in a main application on behalf of the user. Like posting comments on Facebook, or publishing a tweet. This means that "third-party" here is defined from the point of view of the end user. As in "I don't want to give my Facebook password to this random application, but I'd like to allow it to publish status on my behalf". The goal is to give the third-party app an Access Token signed by the authentication server (Facebook in our example). This doesn't take care of authenticating the user.

Can't answer that with authorization alone !

Authentication is enabled by the OpenId Connect protocol that adds a standard for returning an identifier for the user along the access token, that can be decoded and used by the third party app.

In our case, it can be used by our SPA to Authenticate the user against our API and get an access token to perform some actions. Our SPA is not a third-party as defined by OAuth2 since our user doesn't even need to know that the SPA and the API are two different things. However it allows us to treat our API as an authentication service for our spa which has several benefits:

• It scales better in case you DO want to authenticate from other third-party services.
• It allows you to isolate your login form making it more secure

• It allows the implementation of a Silent Authentication for maintaining sessions

  Here's how it looks:

It's important to note that there are several possible authentication flows when using OpenId Connect. Currently the flow that must be used by SPAs is the Authorization Clode Flow with Proof Key for Code Exchange. I won't describe it here, instead I'll do you one better and link to the awsome Auth0 article that goes into . I strongly recommend you do not try to implement this yourself as it's time consuming, and easy to get wrong. Instead use the recommended lib from you framework. For example if you're using the great Django Rest Framework, you can easily add OAuth2/OpenID Connect capabilities with Django Oauth Toolkit for DRF

Maintaining Session

As explained, it is not safe to store the tokens returned by the OpenID Connect flow in the browser. Instead, since you can make use of a Silent Authentication Flow. It works by setting a cookie on the Authentication Server and not prompting the user for their credentials if they are already logged in. CSRF is still an issue here, but since it only concerns the login form, you can use your API framework CSRF token system to mitigate, which is quite easy in most cases.

Pros & Cons

Pros:

• The most flexible set up as you can use it to authenticate third-party App
• Allows the use of federated identiy provider By proxying other Open id provider like Facebook or Google Cons:
• More costly to implement and hard to get right without using a trusted Framework / Library
• I you use a dedictated authentication provider, you might need to subscribe to a paying plan

Backend For Frontend

There is one alternative I haven't listed yet, that opens up new possibilities and new authentication flows. It is the "Backend For Frontend" architecture pattern, which means serving your SPA from a server that can also run code. For example a Meta-Framework like NextJS, or just a regular server that happens to also statically serve your app. Using this solution changes a lot of things. For example, it might be easier to manually mitigate CSRF threats in option 1, or use a cookie to store the tokens created in Option 2.

However I won't go into the details here, beyond the scope of just choosing and Authentication Solution. Instead I might write a dedicated article listing the patterns associated with this architecture

In the meantime, the OAuth2 spec has a great section on the subject if you'd like to know more.

Using an Authentication Provider

Finally, As we've seen with the previous patterns, Authenticating an SPA is not as straightforward as it should be. If you don't want to invest too much time looking for the perfect solution, you can always use an Authentication and Authorization SaaS. Most of them come with out-of-the-box integrations with both you SPA and your framework of choice, which can save you a lot of time. Of course, even though most of them offer a free plan, you might need to purchase a paying subscription as your user base grows.

Most of them rely on OpenID Connect behind the scenes, meaning the integration with your SPA and your API usually look like this:

• Here are a few examples that provide a great DX:
  • Auth0: Awesome service, and great documentation. However it quickly gets expensive;
  • [Firebase auth]: GCP authentication solution. Interesitingly they seems to store some token in IndexDB which is not XSS safe;
  • [AWS cognito]: AWS identiy management solution. Might be a good solution if you're already using AWS;
  • Keycloack: Open source, yay!

Conclusion

As often when it comes to programming, there is no silver bullet for handling Authentication with SPAs. With this article I hope to give you some insight into what's possible so you can find a solution that best suit your needs. And to make this easier, I've compiled what we covered into this handy chart, I hope it helps you in your conception work, it certainly helped me!

I might write some dedicated tutorials on one or more of this pattern so stay tuned !

References

1. MDN CORS documentation
2. The issues with using jwt for maintaining sessions
3. OAuth2 for browser-based apps
4. SameSite cookies
5. Auth0 which auth flow
6. Mitigating CSRF in spas

Welcome to part 4 of this tutorial! Today we'll see how to connect a React app to our awesome FastAPI backend! As always, here's the repository with the code we'll be writing during this article.

Last time we added the following routes to our API:

• /polls/: Lists all the existing questions
• /polls/{id}/: Displays a poll details, including the associated results

Now our goal is to use them to display the same information as in the original Django tutorial, using React:

• An index page for listing the polls
• A Form for each poll
• A Result page for each poll

In fact, since we'll be using React we can go one step further and merge the two last views together in a mutli-purpose detail view with the following specs:

1. First when arriving on /polss/{id}/ the user should see the title of the poll and the available choices
2. Then the user submits their own vote by clicking on one of the choices
3. Finally once the vote is processed by the API, the current vote count is displayed to the user under each choice

As in the Django tutorial, we'll keep the actual vote submission for the next part though !

We'll use Create React App to build our UI in React. CRA is an awesome collection of scripts that take care of bundling, transpiling, and all the boilerplate code you might need setup a React project. This way we can get straight to coding !

Setting up the project

For this tutorial, our UI Will live in the same project than our API. In real life though, you'd probably want to have a separate repository. From the root of the project run the following command to create the UI :

• yarn create react-app ui --template typescript

  OR if you prefer npm

• npx create-react-app ui --template typescript

Note: We'll be using typescript for this tutorial. Don't worry you don't need to have a deep understanding of types to follow along tho, we'll stay pretty basic ! This will mainly prevent us to make mistakes when using data coming from the API.

We'll also need the following libraries to build our UI:

• Axios: An awesome library to make requests.
• React Router: For client side navigation
• react-query: Painless data synchronization with the server
• Material UI: Not necessary, but great to quickly prototype something if youd don't have any design skills. (Like me 👌)

Note: None of these are strictly necessary, but this is of my go to setup when I need to quicly build a small SPA. I must say I'm pretty satisfied with it, but if you have any feedback Reach out on Twitter 🐦!

Our project is ready. Without further ado let's dive in !

I will!

Setting up react-query

We'll start by setting up react-query. React query allows to define a default query function. As we'll only be using useQuery to communicate with our API, we'll set it ot use Axios's GET function. That way we can use our endpoints URLs, both as query keys and argument for axios.

I like to put my query function in an utils folder like so:

// utils/queryFn.ts

import axios from "axios";

// We use the built-in QueryFunction type from `react-query` so we don't have to set it up oursevle
import { QueryFunction } from "react-query";

export const queryFn: QueryFunction = async ({ queryKey }) => {
  // In a production setting the host would be remplaced by an environment variable
  const { data } = await axios.get(`http://localhost:80/${queryKey[0]}`);
  return data;
};

Then we just need to configure the QueryClient to use our default function:

// index.tsx

import React from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";
import reportWebVitals from "./reportWebVitals";
import { queryFn } from "./utils/queryFn";
import { QueryClient, QueryClientProvider } from "react-query";

// Configuring the queryclient to use
// our query function
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryFn: queryFn,
    },
  },
});

ReactDOM.render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>,
  document.getElementById("root")
);

Setting up react router

We also need to setup ou client side routing. As explained in the introduction, we'll create two routes: The Poll index and the Poll details. For now we'll just put some placeholder in there until we get to building the actual views in the next section 😄!

import React from "react";
import { BrowserRouter, Routes, Route } from "react-router-dom";
import PollIndex from "routes/Poll";
import Results from "routes/Poll/Results";

import CssBaseline from "@mui/material/CssBaseline";
import "./App.css";

function App() {
  return (
    <div className="App">
      <CssBaseline />
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<div>Poll Index</div<}></Route>
          <Route path=":questionId/" element={<div>Poll Form</div<} />
          <Route path=":questionId/results/" element={<div>Poll Results</div<} />
        </Routes>
      </BrowserRouter>
    </div>
  );
}

export default App;

Now launch the app with yarn start and both routes should become available!

Now all that's left to do is to build a PollIndex and PollResult components to replace the placeholders! These components will be responsible for querying the API using react-query and display the results !

Building the Poll index

We'll start building the Poll Index. We want to list all the existing polls, and maybe make them link to the corresponding Form while we're at it !

... (To Lip-Sync FOR YOUR LIFE!) to query our endpoints with useQuery!

Types definition

First, since we're using typescript, we need to describe the type we expect to receive from our API. That's where FastAPI automatic documentation really shines in my opinion. When you - or others - want to build something that interface with our API (which should be expected when working on an Application Programming Interface), all you have to do is consult the /docs endpoint.

Let's have a look to both our endpoints:

Here's the documented respone shape for /polls/

And the one for /polls/{id}:

Pretty straightforward, le's translate that into typescript, and we'll be guaranteed to communicate with our API correctly! Here's the types we'll be workgin with:

export interface Choice {
  id: number;
  choice_text: string;
  votes: number;
}

export interface Question {
  id: number;
  pub_date: string;
  question_text: string;
}

export interface QuestionResults extends Question {
  choices: Choice[];
}

We're done with typescript !

Now, I like to put all my pages components inside a routes folder and then mimick the actual route structure of the app. With the latest version of react-router out, I need to check what the current best practices are though!

Create routes/Poll/index.ts, with the following Implementation:

//Poll/index.ts

import React from "react";

// The type we've just defined
import { Question } from "types";
import { useQuery } from "react-query";

// Routing
import { Link} from "react-router-dom";


// Material ui stuff
import { styled } from "@mui/material/styles";
import Card from "@mui/material/Card";
import Typography from "@mui/material/Typography";
import Container from "@mui/material/Container";
import Box from "@mui/material/Box";
import Page from "components/template/Page";

const StyledLink = styled(Link)`
  text-decoration: none;
`;

const PollIndex: React.FunctionComponent = () => {

  // Syncing our data
  const { data: questions, isSuccess } = useQuery<Question[]>("polls/");

  // In real life we should handle isError and isLoading
  // displaying an error message or a loading animation as required. 
  // This will do for our tutorial
  if (!isSuccess) {
    return <div> no questions </div>;
  }

  return (
    <Page title="Index">
      <Container maxWidth="sm">
        {questions?.map((question) => (
          <Box marginY={2}>
            <StyledLink to={`${question.id}/results/`}>
              <Card key={question.id}>
                <Typography color="primary" gutterBottom variant="h3">
                  {question.question_text}
                </Typography>
              </Card>
            </StyledLink>
          </Box>
        ))}
        <Outlet />
      </Container>
    </Page>
  );
};

export default PollIndex;

And then replace the placeholder in App.tsx:

// App.tsx


import PollIndex from "routes/Poll";

...

function App() {
  return (
  ...
  <Route>
    ...

    <Route path="/" element={<PollIndex />}></Route>
  </Routes>
  )
}

The most important bit here is const { data: questions, isSuccess } = useQuery<Question[]>("polls/");. As you can see I'am passing the useQuery hook the expected type of our response. Otherwise data would be of type unkown and we don't want that !

For the rest, displaying the list of question is as easy a mapping over the query results. Let's see how that looks:

Not bad uh ?

Now, now, no need to cry

We'll build the Details view using exactly the same method !

Building the detail page

This one will live next to the Polls/index.tsx page, let's call it Polls/Details.tsx. This time, as this page will be accessed at polls/<poll_id> we'll use the useParam hook from reat-router-dom to retrieve the id, and pass it to our API. Like so :

// Detail.tsx

import React, { useState } from "react";

// types
import { QuestionResults } from "types";

// routing
import { useParams } from "react-router-dom";

// querying
import { useQuery } from "react-query";


// Material ui stuff
import Card from "@mui/material/Card";
import Page from "components/template/Page";
import Chip from "@mui/material/Chip";
import CardContent from "@mui/material/CardContent";
import CardHeader from "@mui/material/CardHeader";
import CardActionArea from "@mui/material/CardActionArea";
import Typography from "@mui/material/Typography";
import Grid from "@mui/material/Grid";


const Details = () => {
  const { questionId } = useParams();

  // This state variable controls
  // displaying the results
  const [hasVoted, setHasVoted] = useState(false);

  // We can use the id from use param
  // directly with the useQuery hook
  const questionQuery = useQuery<QuestionResults>(`polls/${questionId}/`);

  if (!questionQuery.isSuccess) {
    return <div> loading </div>;
  }

  return (
    <Page title={questionQuery.data.question_text}>
      <Grid spacing={2} container>
        <Grid item xs={12}>
          <Typography variant="h2">
            {questionQuery.data.question_text}
          </Typography>
        </Grid>
        {questionQuery.data.choices.map((choice) => (
          <Grid item xs={12} md={6}>
            <Card key={choice.id}>
              <CardActionArea onClick={() => setHasVoted(true)}>
                <CardHeader title={choice.choice_text}></CardHeader>
                <CardContent>
                  {hasVoted && <Chip label={choice.votes} color="success" />}
                </CardContent>
              </CardActionArea>
            </Card>
          </Grid>
        ))}
      </Grid>
    </Page>
  );
};

export default Details;

That's it! Look pretty much the same as the index, we're juste using map over the choices of a specific poll to display them. The results display are controlled using a simple useState hook. However if this data was really sensitive, we'd have to restrict access to it on the server as well !

Just replace the placeholder in App.tsx and admire the result !

// App.tsx


import PollDetails from "routes/Poll/Details";

...

function App() {
  return (
  ...
  <Route>
    ...

    <Route path="/" element={<PollIndex />}></Route>
    <Route path="/" element={<PollDetails />}></Route>
  </Routes>
  )
}

A very scientific survey I made

Looks great !

Thanks for reading !

That's a wrap for part 4! Hope you liked it, next time we'll see how to actually submit the vote to our API and save it to the database! 😃

As always if you have any question you can reach out to me on Twitter 🐦!

References

1. react-query
2. react-router
3. FastAPI

In today's episode of React Tips & Tricks, we'll see how to handle and submit file Data, and how to display a progress bar !

A basic Form

Let's say we need to build a form to create blog posts, with an input for the title, and a textarea for the body.

Here's a simple implementation for such a form, using Material UI for the basic components:

import React, { useState } from "react";
import Box from "@mui/material/Box";
import TextField from "@mui/material/TextField";
import Button from "@mui/material/Button";

interface PostData {
  title: string;
  body: string;
}

const Form: React.FunctionComponent = () => {
  const [formValues, setFormValues] = useState<PostData>({
    title: "",
    body: "",
  });

  // Handlers for the input
  const handleTitleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setFormValues((prevFormValues) => ({
      ...prevFormValues,
      title: event.target.value,
    }));
  };

  const handleBodyChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setFormValues((prevFormValues) => ({
      ...prevFormValues,
      body: event.target.value,
    }));
  };

  return (
    <Box
      display="flex"
      height="100%"
      flexDirection="column"
      justifyContent="center"
      alignItems="center"
    >
      <Box marginY={2}>
        <TextField
          onChange={handleTitleChange}
          value={formValues.title}
          label="Post Title"
          name="title"
        />
      </Box>
      <Box marginY={2}>
        <TextField
          onChange={handleBodyChange}
          multiline
          minRows={5}
          label="Post Body"
          name="body"
        />
      </Box>
      <Box marginY={3}>
        <Button onClick={() => console.log("submit")}>Submit Post </Button>
      </Box>
    </Box>
  );
};

export default Form;

Note: I'm not using any Form libraries here, as I want to focus on file handling. In a production setting I'd really recommend using somethign like Formik to avoid re-inventing the wheel!

This works like a charm, and renders the following output:

Great! But now say we also want to submit an image along with the title and the body, to serve as a cover for the article. This is a bit more complicated as we're not juste maniuplating strings anymore.

Adding an image to the post

In order to be able to submit an image, we need to add 3 things to our Form :

• A button to upload a file from the client's computer;
• A way to handle the file and store it in the sate;
• A handler to submit our form;

Let's dive in !

Adding the button

To add a file upload button to the form, we use an input of type file, wrapped in a Button component :

  //Form.tsx

const Form: React.FunctionComponent = () => {

  ...

  return (
    ...

    <Box marginY={2}>
      <TextField
        onChange={handleBodyChange}
        multiline
        minRows={5}
        label="Post Body"
        name="body"
      />
    </Box>

    <Button variant="contained" component="label">
      <input type="file" hidden />
    </Button>

    <Box marginY={3}>
      <Button onClick={() => console.log("submit")}>Submit Post </Button>
    </Box>
  )
}

Here we leverage the fact that a label (Here rendered as a Button) is programmatically linked to its input. Meaning, any click event on our "Button" component will be passed to the hidden input. This trick allows us to display any component we want to the user, while still benefiting fro the built-in file handling system.

Controlling the component

For now our input is uncontrolled: it's not linked to any state variable, so we can't declaratively use its value when submitting the form. We need to change that :

I agree with Dwight!

To control our input, as with a normal input, we need to pass it a handler. This handler uses the File API to retrieve the fiels data we interested in:

interface PostData {
  title: string;
  body: string;
  image: File | null;
}

const Form: React.FunctionComponent = () => {

  // Add an image attribute
  // to our formData
  const [formValues, setFormValues] = useState<PostData>({
    title: "",
    body: "",
    image: null,
  });
  ...

  // Set up the handler
  const handleImageChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setFormValues((prevFormValues) => ({
      ...prevFormValues,
      image: event.target.files ? event.target.files[0] : null,
    }));
  };

  ...


return (
    ...
      <Button variant="contained" component="label">
        {formValues.image?.name ?? "Upload File"}
        {/* Bind the handler to the input */}
        <input onChange={handleImageChange} type="file" hidden />
      </Button>
    ...
  )
}

Now when the user uploads an image using our button, the image attribute will be populated with a File object. This object has a lot of useful properties, like the name of the file, and its type. We can use them to display the name file currently selected by the user inside our button. Also note that target.files is an array. Here we're only interested in the first value as we're only uploading one file, but the same method can be used with multiple files !

Form submission

Finally, we need a way to submit the data. For testing purposes I've created a small API in Flask you can find it in the repository for this article. It's just a single endpoint that listens for POST requests and returns a 201.

Now, we can't POST our Data as json because we're want to send a file and json doesn't handle binary data. We need to send form-data instead. We'll use axios to send the request, as it comes in handy to display the progress as we'll see in the next section.

Note: Alternatively, we could encode our image in BASE64 and send it as a string in the json payload. Of course in that case we'd also need to decode it in the backend.

  const handleSubmit = async () => {
    const formData = new FormData();
    formData.append("title", formValues.title);
    formData.append("body", formValues.body);
    formValues.image && formData.append("image", formValues.image);

    const response = await axios.post(<YOUR-API-ENDPOINT>, formData, {
      headers: {
        "Content-Type": "multipart/form-data",
      },
    });

    return response.data

  };

Several things are happening here :

• First we create a new FormData object;
• Then we add our fomvalues to the data;
• Finally we post it to our endpoint using the correct content headers

Showing progress

Our form submisssion is working hooray ! But we're not done yet !

Maybe the image our user will posting are going to be heavy, and maybe we'll do some slow processing server side too. As it's probably gonna take some times to process the request, we'd like to show a progress bar.

That's where Axios saves the day! It comes with two built-ins callback hook to process progress data:

• onUploadProgress: send event during the upload phase;
• onDownloadProgress: during the download phase;

Now all we have to do is to create a new state variable to stor the progress value and monitor the requests states ! Might as well write this logic in a custom hook, as we'll probably want to reuse it later. (It's also easier to read). Here's how this looks :

// hooks.ts

import { useState } from "react";
import axios from "axios";

export const useUploadForm = (url: string) => {
  const [isSuccess, setIsSuccess] = useState(false);
  const [progress, setProgress] = useState(0);

  const uploadForm = async (formData: FormData) => {
    setIsLoading(true);
    await axios.post(url, formData, {
      headers: {
        "Content-Type": "multipart/form-data",
      },
      onUploadProgress: (progressEvent) => {
        const progress = (progressEvent.loaded / progressEvent.total) * 50;
        setProgress(progress);
      },
      onDownloadProgress: (progressEvent) => {
        const progress = 50 + (progressEvent.loaded / progressEvent.total) * 50;
        console.log(progress);
        setProgress(progress);
      },
    });
    setSuccess(true)
  };

  return { uploadForm, isSuccess, progress };
};

Here I made the choice to represent the progress as evenly distributed between the uplaod and download steps, but you're free to do as you please ! It all depends on what you want to display to your users. I've also added success boolean we can use to do some conditionnal rendering.

Now all we have to do is use our custom hook to submit the form, and somehow display the progress value! I'm using linear progress for thatfrom Material UI here.

const Form: React.FunctionComponent = () => {
  const { isSuccess, uploadForm, progress } = useUploadForm(
    "http://localhost:5000/post"
  );
  ...

  const handleSubmit = async () => {
    const formData = new FormData();
    formData.append("title", formValues.title);
    formData.append("body", formValues.body);
    formValues.image && formData.append("image", formValues.image);
    return await uploadForm(formData);
  };

}

...

const Form: React.FunctionComponent = () => {
  return (

    ...

    <Box marginY={3}>
      <Button onClick={handleSubmit}>Submit Post </Button>
      <LinearProgress variant="determinate" value={progress} />
    </Box>
  )
}

Here's what it looks like :

Pretty neat !

Bonus Round !

I thought it would be a nice addition to show how to display a little success message after the bar reach 100%.

To do so we'll use our isSuccess indicator. But first well add an artificial pause after the request complete to let he user admire the progress bar reaching 100%. Otherwise React will merge the states updates and dipslay the success message before the progress bar has finished animating.

//hooks.ts

  const uploadForm = async (formData: FormData) => {

    ...

    await new Promise((resolve) => {
      setTimeout(() => resolve("success"), 500);
    });
    setIsSuccess(true);
    setProgress(0);
  };

And now using isSuccess we can conditionnaly render a success message :

{ isSuccess ? (
  <Box color="success.main" display="flex">
    <CheckIcon color="success" />
    <Typography>Success</Typography>
  </Box>
  ) : (
  <>
    <Button onClick={handleSubmit}>Submit Post </Button>
    <LinearProgress variant="determinate" value={progress} />
  </>
)}

Thanks for reading !

That's it for today, hope you learned something ! Form handling in React is not easy, as they are so many ways to do it, and so many ways it could go wrong. All the more reason to keep trying and learning !

Hungry for more React tips ? ➡️ Follow Me on Twitter !

References

1. File API documentation
2. Axios
3. Material Linear Progress Bar

Welcome to part 3 of the tutorial, today we'll see how to use path operations to return information from our Database. It's CRUD time ! We'll start with R though ! 😋

Last time in part 2, we set up our Postgres Database, wrote the models and generated the associated migrations. Today we'll pick up where we left off and start doing something useful with our endpoints: returning some information stored in the DB.

As in the Django tutorial we'll display the list of existing polls, and the associated results. There is one key difference though. Django being a monolithic Framework, it handles both querying the database AND rendering the resulting information to the client using an HTML templating language. FastAPI, however is only concerned with the API side of things, meaning we'll have to build the UI separately.

We'll use React and the excellent create-react-app to build the UI. I initially did both - The CRUD and the UI - in this article, but it ended up being super long so I decided to split it. I'll post the React part later this week so stay tuned ! 🚀

On Today's Menu:

• Creating some CRUD utilities
• Using path operations to expose some information from our database

Crud

It's time to rip the benefits of all the set up we did in part 2. Thanks to our previous work, our database if already fully, set up so run docker-compose up from the root of the project to spin up everything and let's get coding! The first thing we'll do is creating some crud utilities for reading from our database. Well create two functions:

• get_question to fetch a specific question based on an ID;
• list_questions to list all the existing polls

Add a crud.py file in your poll app and write the following code in it:

 # crud.py

from sqlalchemy import select
from sqlalchemy.orm import Session

from polls import models
from polls import schemas


def get_question(db: Session, question_id: int):
    question_query = select(models.Question).where(models.Question.id == question_id)
    question = db.execute(question_query).one().Question
    return question


def list_questions(db: Session):
    question_query = select(models.Question)
    questions = db.execute(question_query).scalars().all()
    return questions

He're we're using a Session object to communicate with the database using our orm, SQLAlchemy. We'll worry about passing a session to our functions later, for now let's just assume we have one. As you can see, SQLAlchemy once again is a bit more explicit in its use than django-orm. The querying syntax looks a lot like SQL, and that's what I like it so much: if you'realready comfortable working with SQL, learning to use SQLAlchemy is a breeze!

Yes I am aware I've written SQLAlchemy 3 times in 3 sentences, and here's another one for your trouble

For example select(models.Question).where(models.Question.id == question_id) is equivalent to the following SQL statement:

  SELECT
   * 
  FROM
    polls_question 
  WHERE polls_question.id = 1

The structure is almost exactly the same, the table name are simply replaced with our models name !

The only thing that might not be obvious here is the way the related choices are fetched. In SQL land we'd need to perform the following join to get the choices associated with each question (and in so doing, creating duplicate questions in the results !).

SELECT 
  *
FROM 
  polls_question as question
  LEFT JOIN polls_choice as choice on choice.question_id = question.id

With SQLAlchemy, the relationship will take care of that for us, as we'll see in the next section !

Pydantic models

Now that our CRUD is ready, we'll also need a way to convert the results into a format that can be send in an HTTP response. Pydantic will take care of that for us ! We already used it in part 2 to load our environment variables, but it can do much more ! If you're familiar with DRF pydantic models, they fill the same functino as DRF's serializers:

• Deserializing and validating input from outside the API
• Serializing and validating output from our endpoints

Regarding validations errors, it's important to note that error raise when deserializing the data from a request will automatically rais a 422 HTTP error, while validation error when serializer the endpionts output will raise an unhandled exception. This is because a validation error when serializing data on which we have complete control point to a configuration error on our part, and not a user error.

One last thing before we dive in: pydantic like SQLAlchemy uses the term "model". This tends to make this kind of tutorial a bit confusing if it's your first time workng with both. Thus from now on, like in the Fastapi doc, I will be refering to Pydantic models as schemas!

With this out of the way, let's write schemas we need to serialize the our CRUD's ouput. Add a schemas.py file to your poll app, and create the following schemas :

# app/polls/schemas.py

import datetime
from typing import List

import pydantic


class Choice(pydantic.BaseModel):
    choice_text: str
    votes: int

    class Config:
        orm_mode = True


class Question(pydantic.BaseModel):

    id: int
    question_text: str
    pub_date: datetime.datetime

    class Config:
        orm_mode = True


class ReadQuestionChoices(ReadQuestion):
    id: int
    question_text: str
    pub_date: datetime.datetime
    choices: List[BaseChoice]

    class Config:
        orm_mode = True

Contrary to DRF theres is no out-of-the-box way to generate the schemas from the ORM declaration. However as you can see the Question schema and the Question model, are very similar. This is not ideal, as this can lead to a bit of code duplication.

Tiangolo, the author of FastAPI, got us covered tho ! A few months ago he released SQLModel, a library that aims to fill that gap by wrapping Pydantic and SQLAlchemy. I will not dive more into it for now, , as I believe it's important to understand the problem a tool is designed to solve before using it! I might do a dedicated article later in this tutorial though !

Of note here is the use of nested schemas, and the orm modes. Setting orm_mode to true means that pydantic will know to access the attributes with the object.attribute syntax rather than dict['key']. And when accessing the choices attribute, SQLAlchemy will take care of making the necessary joins, which will offer us a nice nested structure where each question is associated with an array of related choices.

One last thing: you might have noticed than ReadQuestion and ReadQuestionChoices have most of their attributes in common, which is not very DRY. Pydantic support inheriting from existing schemas though, which means we can re-write it like that:

import datetime
from typing import List

import pydantic


class BaseChoice(pydantic.BaseModel):
    choice_text: str
    votes: int

    class Config:
        orm_mode = True


class BaseQuestion(pydantic.BaseModel):
    question_text: str
    pub_date: datetime.datetime

    class Config:
        orm_mode = True


# We only include the id when reading
# That way we can reuse base question
# When creating our write schemas
class ReadQuestion(BaseQuestion):
    id: int


class ReadQuestionChoices(ReadQuestion):
    choices: List[BaseChoice]

There all good !

Building the Endpoints

Now we've got all the tools we need to create our path operations !

We'll need to read endpoints:

• An endpoint to list the existing questions: /polls/;
• And endpiont to dipslay the details of the questins: /polls/{id}

In the Django tutorial, more views are built, because the views are also responsible for rendering the UI, so there need to be at least one per page. However, we're not building a monolith here ! The pages will be created in React in part 4, and the form and result page, for example, will both use the GET /polls/{id} endpoint to fetch the data they need.

In polls/endpoints.py create those two path operations :

# polls/endpoints.py

from typing import List

from . import schemas
from . import crud

@router.get("/", response_model=List[schemas.ReadQuestion])
async def index():
    return crud.list_questions(db)


@router.get("/{id}/", response_model=schemas.ReadQuestionChoices)
async def question_detail(id: int):
  try:
      return crud.get_question(db, id)
  except NoResultFound:
      raise HTTPException(
          status_code=404,
          detail="Token does not exist",
      )

There are a few things going on here:

• We've added a second argument to the router.get call : the response_model. This response model will be applied to the value returned by the path operation, before sending the response to the client. We're using the List type from the standard typing package to specify that we returns several questions in the index.
• In the question_detail path operation, we specify the {id} in the router url, and FastAPI is smart enough to automatically pass it as the first parameter to our path operations !
• We're using fastapi HTTPException to automatically return a 404 error if there is no question matching the providing ID.

The type int and path parameters are also used by FastAPI to generate the automatic documentation !

However, If you've been paying attention you might have noticed that something is missing. Our crud utils need a Session objects to communicate with the database. We're passing them a variable called db here, but it's not defined anywhere yet !

To retrieve this Session objects, we'll use one of FastAPI main selling point: its dependency injection system !

What is dependeny injection ?

If you've alredy work with a Framework before, you should be familiar with the term. Dependency injection is a form of inversion of control that allows a "client" to specify the dependencies it needs an trust that an other agent, oftenime the framework, will provide them at the right time.

For example in Django's view, the self.request object available in Class Based view is a dependency injection pattern ! Hope this clears at up !

Isn't it ?

The dependency we're looking to inject is a Session. To do so, we declare a function that returns a session using the SessionLocal we created in database.py we created in part 2

# polls/endpoints.py


# Database session as a dependency
def get_db():
    db = database.SessionLocal()
    try:
        yield db
    finally:
        db.close()

The code after the yield instructions will be execute right after our path operation is done sending the response. This way we can make sure the session is closed correctly ! Now we can use the Depends function providing from FastAPI:

# polls/endpoints.py


...

from fastapi import Depends

...


@router.get("/", response_model=List[schemas.ReadQuestion])
async def index(db=Depends(get_db)):
    return crud.list_questions(db)


@router.get("/{id}/", response_model=schemas.ReadQuestionChoices)
async def question_detail(id: int, db=Depends(get_db)):
    try:
        return crud.get_question(db, id)
    except NoResultFound:
        raise HTTPException(
            status_code=404,
            detail="Token does not exist",
        )

Now everything should be working ! You can try out your endpoints using the automatic documentation available at localhost/docs. Create a few questions using PGAdmin or a psql client to create a few questions and choices, and try it out ! Everyting should be working smootlhy, and Swagger should display some information about the reponse form that matches our pydantic schemas.

Awesome ! There is one last thing to do before we conclude. If we want to be able to make request from our UI to our API in part4, we need to take care of these pesky CORS headers. In the past setting those headers correctly as been the cause of many headaches, for many developers. With FastAPI howerver, nothing's more simple ! We just need to use the CORSMiddleware in main.py:

# main.py

...

from fastapi.middleware.cors import CORSMiddleware


origins = ["http://localhost:3000"]

...

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

...

Great ! Now we're ready to build an UI to talk with our brand new API !

Conclusion

That's it for today, hope you enjoyed it ! Part 4 we'll be coming soon, and we'll be focused on building an UI for our endpoints using React. I'm still debating if I should put everything React-relate into specific articles, I'd be glad to know what you think. Let me know on Twitter, you feedback is invaluable !

References

1. FastAPI CRUD
2. Pydantic Documentation
3. SLQModel

As usual the source for this part is available on Github

Here's what's on the menu :

• Spinning up a Postgres Database using docker-composedatabase)
• Installing our ORM of choice: SQLAlchemy
• Writing the Question and Choice model for the poll app

Note: In the original Django tutorial, this is also where django-admin is introduced. For our own admin dashboard we'll be using react-admin which will be presented in a later part of this series !

Requirements

We'll be using docker-compose to run our databse as a service. If you haven't installed it yet, the instructions are available here !

You don't have to use docker-compose to follow along though. If you prefer to set up your PostgresSQL server yourself, just skip directly to Instaling the ORM

💽 Spinning up the database

First of all, we need a database to work with. I chose docker-compose to run a Postgres image along with our app. Our API is already dockerized so this will make it easy to managage everything.

I will not dive into the specifics of docker-compose as it's beyond the scope of this article. However if you've never used it before, I encourage you to go read th documentation. It's quite extensive !

Add a docker-compose.yml at the root of you project, with the following instructions :

  version: "3.9"
  services:
    web:
      build: .
      depends_on:
        - db
      ports:
        - "80:80"
      env_file:
        - postgres.env
        - .env
      volumes:
        - ./app:/app
    db:
      image: postgres
      restart: always
      volumes:
        - data-volume:/var/lib/postgresql/data
      env_file:
        - postgres.env
    pg_admin:
      image: dpage/pgadmin4
      environment:
        - PGADMIN_DEFAULT_EMAIL=user@domain.com
        - PGADMIN_DEFAULT_PASSWORD=password
      ports:
        - "81:80"
  volumes: 
    data-volume:

This configuration will launch the following:

The web service

This is our api running on the port 80. We mount the /app folder containg the app code into the container so we don't have to rebuild it everytime we make a change.

We also include two environment files:

• postgres.env: This will hold the database credentials

• .env: For environments variables specific to the web servcie

  The db service

  This service runs a postgres image using the same postgres.env than the API to configure the database. That way we can keep our environment variables DRY. It also uses the data-volume declared at the end of the file to persist the data.

  The pg_admin service

This runs a pgAdmin admin image. pgAdmin is an adminisitration tool for PostgreSQL database. Declaring it as a service will make configuring the server connection eaiser as we'll benefit from docker-compose custom network. We expose it on port 81 to avoid conflicting with the API running on the port 80.

To configure the postgres image, create the postgres.env file at the root of the project, with the following variables :

 #postgres.env 

  POSTGRES_PASSWORD=password
  POSTGRES_USER=poll
  POSTGRES_DATABASE=poll
  POSTGRES_HOST=db

We'ready to launch everything! Just run docker-compose up and you should see the output for each service. Now you can access pgAdmin at localhost:81. To connect to the postgres database, simply add a new server and enter information from postgres.env like so :

That's it !

Now that our environment is up and running in let's dive in !

⚙️ Configuring our ORM: SQLAlchemy and Alembic

Contrary to Django, FastAPI doesn't ship with a built-in ORM solution like django-orm. FastAPI focuses on enabling you to build perfomant and robust APIs super efficiently, and let you make your own choices for everything else. You could avoid relational databases altogether and use MongoDB for instance. This lets you build an architecture tailored to your needs.

It does mean that we have to configure our ORM ourserlves though. For this tutorial we'll use SQLAlchemy, a reliable solution under active developement.

First let's install a few dependencies. From you app folder run poetry add sqlalchemy psycopg2-binary alembic pydantic. Besides SQLAlchemy this will install the followingd packages:

• psycopg2: A python adaptater for PostgresSQL. Required by SQLAlchemy (And also by Django when working with Postgres)
• alembic: This will be our migrations management tools
• pydantic: Data validation and settings management using python type annotations. If you've worked with DRF before, you can think of pydantic models as the equivalent of serializers.

Using environment variables :

We will need to access the environement variables in order to set up the connection with the database. We'll use a special pydantic class called BaseSettings. Add a config.py file to app/app with the following code :

#app/app/config.py

from pydantic import BaseSettings


class Settings(BaseSettings):
    POSTGRES_USER: str
    POSTGRES_PASSWORD: str
    POSTGRES_DATABASE: str
    POSTGRES_HOST: str

When instantiating the class with settings = Settings(), pydantic will read the variables from the environment and validate them against the types we defined, raising an error if anything is missing. This class is actually a great selling point of pydantic, offering tons of other functionalities like automatic parsing of list and dict type. More information is available here.

SQLAlchemy

Let's configure SQLAlchemy to connect to our Database. Create app/app/database.py and put the following code in it :

# app/app/database.py

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

from . import config


# The declarative base we'll use to create our model 
Base = declarative_base()

For now all we're concerned with is writing the models, so we only need to configure the declarative base from which they will inherit. In part 3 we'll come back to this file to create a session maker to use in our path operations.

Alembic ⚗️

Last bit of configuration before writing the models: Alembic. This is SQLAlchemy own migration manager. It will allows us to do the same thing than django's makemigrations and migate commands, but we need to initialize it first !

Let's first generate the configuration files for alembic. From the root of the project cd into the app directory and run alembic init. This will create the configuration scripts for alembic. Your project strucutre should now look like this :

We also need to let Alembic know where to find this scripts, so we can run the commands from the root of the project. We can do so by setting the ALEMBIC_CONFIG environment variable :

//.env

ALEMBIC_CONFIG=/app/app/alembic.ini

Now let's edit the env.py file to configure the connection to the database. If you open this file, you'll see that it's mostly composed of two functions, corresponding to the two available modes of alembic:

• run_migrations_online: Configure the online mode. This is the one that we will be using.
• run_migrations_offline: Configure the offline mode. This mode allows the user to generate SQL instructions instead of running the migrations directly against the database

In both case, we need to edit the way the connection URL is set up. Instead of reading it from alembic.ini we'll use the Setting class we created earlier to generate it from our environement variables. Like so :

  from app.config import Settings

  settings = Settings()

  ...

  def run_migrations_offline():

    ...

    url = f"postgresql://{settings.POSTGRES_USER}:{settings.POSTGRES_PASSWORD}@{settings.POSTGRES_HOST}/{settings.POSTGRES_DATABASE}"

    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
        compare_server_default=True,
    )

  ...

  def run_migrations_online():

    ...

    url = f"postgresql://{settings.POSTGRES_USER}:{settings.POSTGRES_PASSWORD}@{settings.POSTGRES_HOST}/{settings.POSTGRES_DATABASE}"
    connectable = engine_from_config(
        {"sqlalchemy.url": url},
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

To try it out, drop into the web container, and run alembic revision -m "test revision". This will create an empty revision in the file alembic/version folder :

"""test revision


Revision ID: 2af1b91bea53
Revises: 27259876f63d
Create Date: 2021-11-12 18:21:26.442182

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = '2af1b91bea53'
down_revision = '27259876f63d'
branch_labels = None
depends_on = None


def upgrade():
    pass


def downgrade():
    pass

If the file is generated wihtout errors, then Alembic is correctly configured ! You can delete this revision safely, we'll generate a new one from the models in a moment.

Now we're finally ready to write our models and generate the associated migrations !

📝 Writing the models

We'll need two model for our Poll app :

• A Question model : This will hold the question text
• A Choice model: A possible answer for a question.

There is a one-to-many relation between a Question and a Choice

To create them, add a models.py file to the poll folder, with the following code in it :

#/app/polls/models.py

from datetime import datetime

from sqlalchemy import Column
from sqlalchemy import DateTime
from sqlalchemy import ForeignKey
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy.orm import relationship

from app.database import Base


class Question(Base):
    __tablename__ = "poll_question"

    id = Column(Integer, index=True, primary_key=True)
    question_text = Column(String(200), nullable=False)
    pub_date = Column(DateTime, nullable=False, default=datetime.utcnow)

    choices = relationship("Choice", backref="question")


class Choice(Base):
    __tablename__ = "poll_choice"

    id = Column(Integer, index=True, primary_key=True)
    choice_text = Column(String(200), nullable=False)
    votes = Column(Integer, default=0, nullable=False)
    question_id = Column(Integer, ForeignKey("poll_question.id"))

If you're coming from Django, it's important to note a few key differences with django-orm:

• You have to set the tablename yourself with the __tablename__ class attribute. Here I followed the Django convention <app_name>_<model_name> but you're free to do as you please !
• We also need to designate a column to serve as the primary key.
• The column are nullable by default, we have to explicetly set nullable=False
• Relationships need to be explicitely declared with the relationship functions. This enables ORM features like loading a question's choices using question.choices

As you can see, SQLAlechmy is a bit more "low level" than Django-ORM which means it needs more configuration. However, it also means that you have a more fine-grained control over its behavior, and as we'll see later in this tutorial it makes querying more explicit!

Now that our models are declared let's see how we can automatically generate the corresponding migrations with Alembic.

the great migration

To automatically generate our migrations, we need to let Alembic know about our models. To do that, we'll simply import them into our env.py file. This is a bit like registering a new app into a django app settings.py.

We also need to import Base, as it is our declartive base that contains all the information for building the tables corresponding to our model. Each time a class inherits from Base, it adds its own instructions to Base.metadata. These instructions are passed to Alembic through the target_metadata variable, so we need to assign it to Base.metadata.

#app/app/alembic/env.py

# We import the models and our declartive base
import polls.models
from app.database import Base

... 

# Find this line near the top of the file 
# And replace None with Base.metadata
target_metadata = Base.metadata

All done ! Run alembic version --autogenerate -m "create question and choice models" to automatically creathe the migration file. It should generate the following instructions :

"""create_question_and_choice

Revision ID: 27259876f63d
Revises: 
Create Date: 2021-11-11 10:52:50.386678

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = '27259876f63d'
down_revision = None
branch_labels = None
depends_on = None


def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('poll_question',
    sa.Column('id', sa.Integer(), nullable=False),
    sa.Column('question_text', sa.String(length=200), nullable=False),
    sa.Column('pub_date', sa.DateTime(), nullable=False),
    sa.PrimaryKeyConstraint('id')
    )
    op.create_index(op.f('ix_poll_question_id'), 'poll_question', ['id'], unique=False)
    op.create_table('poll_choice',
    sa.Column('id', sa.Integer(), nullable=False),
    sa.Column('choice_text', sa.String(length=200), nullable=False),
    sa.Column('votes', sa.Integer(), nullable=False),
    sa.Column('question_id', sa.Integer(), nullable=True),
    sa.ForeignKeyConstraint(['question_id'], ['poll_question.id'], ),
    sa.PrimaryKeyConstraint('id')
    )
    op.create_index(op.f('ix_poll_choice_id'), 'poll_choice', ['id'], unique=False)
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_index(op.f('ix_poll_choice_id'), table_name='poll_choice')
    op.drop_table('poll_choice')
    op.drop_index(op.f('ix_poll_question_id'), table_name='poll_question')
    op.drop_table('poll_question')
    # ### end Alembic commands ###

Always check the migrations generated by Alembic to verify that everything is correct. You can find more information about what alembic can auto-generate here

Everything checks out, now run alembic upgrade head to apply the migration, then head over to pgAdmin, and you should see the new tables !

Congrats ! You're models are ready !

Conclusion

Thats all for today, hope you enjoyed it! Now that we've set up our relational database, in part 3 we'll see how to communicate with in it our path operations using SQLAlchemy session.

In the meantime you reach out to me on Twitter. Questions and feedback are most welcomed !

References

1. FastAPI database docs
2. SQLAlchemy docs
3. Alembic docs
4. docker-compose

Recently, I decided the time had come for an overhaul of the way we handle software architecture in my team. As our numbers grow, we had an urgent need for tools and processes that allowed us to keep our agility, while offering strong guarantees on the quality of our codebase.

After some research, I settled on a process based on the C4 model and Archi. I am quite satisfied with it, so I figured I'd share it! First we'll go over what thoses tools are, and how to use them. Then we'll apply them to a pratical example: Modeling the Poll App from my on going FastAPI tutorial!

The models for the poll app are also available in this repository

📋 The Specificiations

First let's go over our needs. We're looking for a software architecture method with the following characterisitcs :

• Flexible enough to be used in an agile environment
• Easy to adopt for both senior and junior developers
• Collaborative
• Reusable and Maintainable

I feel the last point is most difficult to attain. Without the right tools, it's hard for a team to go beyond the initial drawing created during the conception phase, and actually maintain a model representative of the current codebase.

With that in mind, let's see how the C4 + Archi combination fits the bill !

🔧 The Tools

The C4 Model

So what is the C4 model ?

The C4 model is a set of software architecture viewpoints designed by Simon Brown. The official documentation (which I encourage you to read 👓) describes it as :

The C4 model is an "abstraction-first" approach to diagramming software architecture, based upon abstractions that reflect how software architects and developers think about and build software.

A C4 model for a given system is composed of 4 diagrams, representing 4 different levels of abstraction. Each lower level diagram "zoom in" on a concept from the previous higher level one. Here's a brief description of each of them:

• Context Diagram: This is the most abstract level. It shows how a system interacts with its users and other systems

• Containers Diagram: Shows the runtimes that power the system. For example a database is a container.

• Components Diagram: Displays the logical units that make up a container and their relationships. What a "logical unit" is depends on the use case, and what you're trying to show in this diagram.

• Code Diagram: This would show the exact implementation of each component. However it would be really tedious to maintain. Instead, this is where the expertise of the engineering team and the best practices in place should kick in.

The 4 levels of the C4 model

A note on UML

You might notice some similarities with the Unified Modeling Language. While it serves a similar purpose, the C4 model is simpler and way more flexible, which it makes its adoption by a team more likely.

This is actually my issue with UML. While its extensive specification might sound good in theory, in practice it is quite heavy to use. In my opinion, unless you're working with a waterfall methodology with a long period dedicated to creating the models, and tools that can auto-generate code from UML, the payoff is jut not worth the trouble.

Of course this doesn't prevent you from using complementary diagrams coming from UML if you'd like to. Personnaly I find the Sequence Diagram often comes in handy !

Archimate & Archi

Now that we've talked about the model (or rather meta-model, as the C4 is a tool for building models), let's see how we can go about producing the diagrams. Remember that we want actual modeling capablilites here, not a simple drawing tool. Simon explains it well, modeling allows to easily reuse the same concepts across different views, and enable a static analysis of your architecture.

To generate our models we'll use the following:

• Archimate : It is an open specificiation modeling language. This is the language that our models will be written in.
• Archi: an archimate editor. This makes working with archimate models super easy !

What I love about Archimate and Archi, is that it maintains a clear separation between model and view, while still offering a great WYSIWG editor.

🎓 The Methodology

Now that we've got the tools, let's see about using them !

Collaboration and Versionning

First of all, for our models to be maintainable, we need to be able to collaborate on them. The great thing about using a modelling langage like archimate instead of boxes and arrows, is that we can version our architecture. All we need to do is to store our models in repositories and we can even create pull request to discuss the changes !

The only issue is that the archimate files genreated by Archi aren't very git friendly. Each model is stored in a huge .xml file which can makes conflicts really hard to solve. Luckily, there is a plug-in that can take care of that for us : CoArchi. CoArchi put each archimate concept into its own file, making PR way easier to read !

Using The C4 Meta-model In Archi

So now we can collaborate, but how do we actually create the C4 diagram in Archi?

Our method for this is heavily inspired by this excellent article, which explains how to map Archimate concepts to the C4 meta model. We can actually save these Mapping in a dedicated model, and use a view as a toolbox from where we can copy paste the C4 building blocks as needed. Here is the end result :

• The C4 persons are maped to an archimate business actors
• The C4 software systems and containers are mapped to archimate application components
• The C4 components are mapped to application functions

Extending The C4 Model

I won't go into too much details here, because it really depends on your organisation, but I think it's good to extend the C4 model with your own set of rules to better suit you needs.

For example in my team we agree on the following :

• In containers diagrams relationship must include the protocol (HTPPS, SSH..) used by the containers to communicate

• In the component diagrams the presence of a relationship between component alwasy imply the existence of a public api/method/attribute

  We even have special rules for describing React apps:

  • Coumpound components are described using composition relation ship
  • .. on so on.

Putting Everything in Practice

Finally let's have a look at a concrete example. Here's how I would describe the architecture of the Poll app from my FastAPI tutorial, using the methods outlined in this article.

The Context

First let's describe the context for our Poll App. In a real life situation I would discuss this diagram with my Product Manager to be sure we are aligned on the systems affected by the project:

Context Diagram

This is pretty self explanatory, here our Poll App is used by both an administrator responsbile for creating the polls, and the end user that answer them. I've also included an imaginary "stats app" to show inter system relationships.

The Poll App Container

Now let's zoom in and explore which containers are necessary for our app. Here we decide what kind of technologies will be necessary for our projects, and how everything will interacts.

Container Diagram

In this case we're using a rather classic paradigm with an API hosting the business logic and an UI handled by SPAs.

The Poll Api Components

Let'ts zoom agin, this time on the API container. In a real life scenario, depending on the complexity of the SPAs, I'd also create a component Diagram for the UI containers.

Component Diagram

To be honest, this one feels a bit overkill for our Poll APP, as it is a very simple use case. Usually in situation with more complex business logic to implement, I'd probably have a single CRUD component.

Conclusion

Thanks for reading, I hoped you found this article useful ! How do your team handle Software Architecture in an agile environment ? Let me know in the comments or on Twitter !

References

1. C4 model website
2. Archimate
3. Archi
4. Archi Collaboration Plugin

Thus, I thought it could be interesting (and fun !) to re-recreate the well known polls app from the Django tutorial, but this time using FastAPI and React ! In this multi part series I'll try to follow the same path as the original as much as possible, although I'll probably split some parts in two to avoid an overload of information.

Today is part 1 : Setting up the project, creating the polls app and making your first django view path operation

The code for this part is available here but I encourage you to code along instead !

🔧 Setting up the project

FastAPI is quite easy to setup, in fact all you need to run a FastAPI app is a singe file instantiating the main app and an ASGI worker to run it. Of course we'll go a bit further. We'll run the app in a Docker container so you'll need to have it installed on your machine

The docker image

First we need to install a few dependencies and we'll use poetry to manage them. Poetry is a modern package manager for python, that also helps you setup your virtual environment. If you don't have poetry, don't worry ! The installation instructions are straightforward, and its use is pretty intuitive.

To initialize the project run poetry init and follow the instructions. The packages we want to install are :

• FastAPI: The FastAPI framework ❤️
• Uvicorn: The ASGI server that will run our app

Once you're done you should see a pyproject.toml file at the root of your project resembling that one:

#pyproject.toml

[tool.poetry]
name = "fastapi-poll-1"
version = "0.1.0"
description = ""
authors = ["io.io"]

[tool.poetry.dependencies]
python = "^3.8"
fastapi = "^0.70.0"
uvicorn = "^0.15.0"

[tool.poetry.dev-dependencies]
black = "^21.9b0"
reorder-python-imports = "^2.6.0"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Now let's create a the Dockerfile for our app! You can create it at the root of your working directory, and add the following instructions in it:

FROM python:3.9

WORKDIR /app

# Install Poetry
RUN curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | POETRY_HOME=/opt/poetry python && \
    cd /usr/local/bin && \
    ln -s /opt/poetry/bin/poetry && \
    poetry config virtualenvs.create false


# Copy using poetry.lock* in case it doesn't exist yet
COPY ./app/pyproject.toml ./app/poetry.lock* /app/

RUN poetry install --no-root --no-dev

COPY ./app /app


CMD ["uvicorn", "app.main:app", "--reload", "--host", "0.0.0.0", "--port", "80"]

This needs a bit of commenting.

The way dependencies are installed might seems a bit strange. We need to first install poetry, then run install without creating a virtual env (that --no-root bit). What's great about this approach is that you can use the same pyproject.toml in your developement environment so things like static analysis tools uses the same dependencies. In a production settings we would probably creat a multi-stage build and discard poetry to have a slimer image.

The app folder will be created in the next section that's where our code will live.

Finally, notice the --reload option we pass to uvicorn which will allows us to work without having to restart the worker everytime we make a change.

We'll launch the container a bit later, first we need to initialize the app !

The fastapi app

First things first, let's create the folder where our code will live: mkidr app

Now as I said we'd only need to create a main.py file if we wanted to. But to stay true to the theme of this serie, I'd like to create a directory structure similar to django apps. That's why we'll create a second app directory that will be our "main" app. Later we'll also create a polls directory.

For now simply run mkdir app/app to create the folder, and create a main.py file inside of it. Your directory strucutre should now look like this :

Perfect ! And now buckle up as the obligatory hello world ! is approaching. Inside main.py write the following lines :

from fastapi import FastAPI


app = FastAPI()


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

This will initialize the app and create our first path operation. This one is straight from the docs ! But you can't see the message yet as we still need to launch the container. We're almost there, head over to the next section !

Launching the app

Before launching the app we need to build the image first. From the root of your project run docker build -t poll-app .

Now we can launch the container: docker run -it -p 80:80 -v "$(pwd)"/app:/app poll-app. This will also mount our app directory so we don't have to recreate it each time we edit the files.

We're now ready to test our endpoint. In your browser navigate to localhost and behold !

... general kenobi

Now that's already good, but what is great is that FastAPI comes with a built in and Swagger for which the open api configuration is autogeneated. That means that if you go to localhost/docs you'll see the following :

FastAPI automatically generate your endpoint documentation ! Pretty neat feature for an API to have if you ask me.

📜 Creating a poll app

Now that Hello world ! is out of the way (I recommend adding it to your personnal collection), let's get to the actual polls app. As I mentionned earlier we'll create a polls directory along side the main app. Once that's done add a file called endpoints.py to this new folder, your project' structure should look like that :

Don't forget to create the relevant __init__.py file so the folder are recognized as Python modules

Now let's create an index for our polls app. This index will later be responsible for listing the available polls in our database but for now it will return a simple message. Add the following code to the polls/endpoints.py:

  from fastapi import APIRouter

  router = APIRouter()


  @router.get("/")
  async def index():
      return {"message": "polls index"}

Here we use APIrouter to declare our path operations. It works exatcly the same as the FastaAPI(). Now all we need to do to make our endpoint available, is to declare it in main.py:

import polls.endpoints

app.include_router(polls.endpoints.router, prefix="/polls")

The prefix indidates that all the routes coming from the polls endpoints start with polls. Your polls index should now be available both at localhost/polls and in the Swagger documentation ! Let's take a look !

Great ! Our polls index works, although it doesn't return anything yet, we'll chnage that in part 2!

Conclusion

That's is for part 1, let me know if you found it useful ! In part 2, we'll see how to set up an actual database to store our polls !

However it does mean that you have to set up yourself some things that usually comes out of the box in other frameworks. For example, if you want to use a relational database, you'll have to choose and install an ORM. SQLAlchemy is the one documented by Fast API. There is a guide to help you set it up, and a tutorial wich gives some indications on how to go about testing it. But if like me, you come from Django, you might still struggle to configure everything so that each test works in isolation, and leaves the database as it was before running.

That's what we'll be covering in this article !

The code presented in this article is fully available on Github. Simply clone the repo and call docker-compose up to launch everything.

Setting up The project

First things first, we need something to test ! We'll create a small project with an endpoint to create an "Item" with a title and a description and store it in the database. I personnaly prefer to use docker-compose to run a Fastapi image as well as a Postgres database next to it. But it's not mandatory.

Let's get to it then !

Setting up SQLAlchemy

SQLAlchemy works by creating a declarative base, which allows us to describe our Database tables as Python classes that inherits it. Let's configure it in a file called database.py:

    # database.py

    from sqlalchemy import create_engine
    from sqlalchemy.ext.declarative import declarative_base
    from sqlalchemy.orm import sessionmaker

    # We're using postgres but you could use
    # any other engine supported by SQlAlchemy
    SQLALCHEMY_DATABASE_URL = "postgresql://test-fastapi:password@db/db"

    engine = create_engine(
        SQLALCHEMY_DATABASE_URL
    )
    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

    Base = declarative_base()

Now we can create our Item model by inherting Base

Models, schemas, and CRUD utils

For our Item model, we simply create a file called models.py and declare it using the Base we've juste configured :

      # models.py


      from sqlalchemy import Column
      from sqlalchemy import Integer
      from sqlalchemy import String

      from .database import Base


      class Item(Base):
          __tablename__ = "items"

          # Don't forget to set an index ! 
          id = Column(Integer, primary_key=True, index=True)

          title = Column(String, index=True)

          description = Column(String, index=True)

We also need to define the corresponding Pydantic schemas. FastAPI uses them to perform validation and serailization :

    # schemas.py
    from typing import Optional

    from pydantic import BaseModel


    class ItemBase(BaseModel):
        title: str
        description: Optional[str] = None


    class ItemCreate(ItemBase):
        pass


    class Item(ItemBase):
        id: int

        class Config:
            orm_mode = True

And finally some CRUD utils for handling our Item instances :

    # crud.py

    from sqlalchemy import select
    from sqlalchemy.orm import Session

    from . import schemas
    from .models import Item


    def get_items(db: Session):
        items = select(Item)
        return db.execute(items).scalars().all()


    def create_item(db: Session, item: schemas.ItemCreate):
        db_item = Item(**item.dict())
        db.add(db_item)
        db.commit()
        db.refresh(db_item)
        return db_item

Now that we're done with everything database related, we can create the endpoint that we'll be testing !

The endpoint itself

Create a main.py file and add the following lines to it :

      # main.py

      from typing import List

      from fastapi import Depends
      from fastapi import FastAPI
      from sqlalchemy.orm import Session

      from . import crud
      from . import models
      from . import schemas
      from .database import engine
      from .database import SessionLocal

      app = FastAPI()

      # Here we create all the tables directly in the app
      # in a real life situation this would be handle by a migratin tool
      # Like alembic
      models.Base.metadata.create_all(bind=engine)


      # Dependency
      def get_db():
          db = SessionLocal()
          try:
              yield db
          finally:
              db.close()

      @app.post("/items/", response_model=schemas.Item)
      def create_item(item: schemas.ItemCreate, db: Session = Depends(get_db)):
          return crud.create_item(db, item)

Notice that we pass the SQLAlchemy Session as a dependency to our endpoint. This is important to note as it'll help us easily test our endpoint as we'll see in the next section.

We can check that our endpoint works thanks to the Swagger available on the /docs endpoint. Another awesome feature of FastAPI !

That's great! But our goal here is to test the endpoint automatically with some unit tests. We need to make sure that our tests don't affect the main database. We also want them to be deterministic and reusable, let's see how to do exactly that !

Testing the endpoint

Basic testing

First let's try the method described in the official documentation. The idea here is to leverage FastAPI Dependency system. Since our endpoint receives its session by dependency injection, we can use Dependency overrides to replace it with a session pointing to a test Database.

To to that, create a file called test_database.py to write our tests, and add the following code to it :

  # test_database.py
  SQLALCHEMY_DATABASE_URL = "postgresql://test-fastapi:password@db/test-fastapi-test"

  engine = create_engine(SQLALCHEMY_DATABASE_URL)
  TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

  def override_get_db():
      try:
          db = TestingSessionLocal()
          yield db
      finally:
          db.close()

  app.dependency_overrides[get_db] = override_get_db

This will replace all instances of the get_db dependency with the override_get_db which return a Session connected to our test database. This does one aspect of what we're looking for: we can run ou tests without affecting our main database.

Let's write a test and run it with pytest to see if that works as expected.

def test_post_items():

    # We grab another session to check 
    # if the items are created
    db = override_get_db() 
    client = TestClient(app)

    client.post("/items/", json={"title": "Item 1"})

    client.post("/items/", json={"title": "Item 2"})

    items = crud.get_items(db)
    assert len(items) == 2

It works perfectly ! Or does it ? We also want our tests to be deterministics, so if we run pytest again we should get the same result...

But we dont ! The items created the first time we ran the test are still in the database, so now we have 4 of them instead of 2. Now, we could delete the items manually. However, this is not something we want to do, because this will become really tedious to maintain once we have more tests that validate more complex behaviors.

Luckily for use there IS a better way !

Enter transactions

To solve our problem we'll make use of SQL Transactions. Essentially transactions are a way to keep a set SQL instructions private to other database connections, until they are commited. And, if the changes should not be commited, they can be rolled back ! Let's add try to add that to our dependency override. Disclaimer the following block of code doesn't actually works, we'll see why in a minute :

    # The following doesn't work
    # changes won't be rolled back !
    def override_get_db():
        try:
            db = TestingSessionLocal()
            db.begin()
            yield db
        finally:
            db.rollback()
            db.close()

    app.dependency_overrides[get_db] = override_get_db

In a FastAPI dependency, everything that comes after the yield instuction is executed after the path operation has run. So that's a great place to try to roll back the changes made during the test. This looks good, but as I said, it doesn't work yet

That's because a call to commit always commit the outermost transaction, so we can't nest transactions thath way. This is a conscious choice from the SQLAlchemy developers to avoid creating confusing and hard to predict behaviors.

Luckily for us they have provided an escape hatch designed to be used test suites. Indeed, a Session can be bound to an existing transaction, by opening it this way :

    def override_get_db():
      connection = engine.connect()

      # begin a non-ORM transaction
      transaction = connection.begin()

      # bind an individual Session to the connection
      db = Session(bind=connection)
      # db = Session(engine)

      yield db

      db.rollback()
      connection.close()

And this time it will work !

Now we can run our test as many times as we want, and it will always pass. But we're not quite done yet. This works for data created by the endpoint, but what if we wanted to seed the database during our test, say for testing an endpoint listing the available items ? The dependency override won't work in this case, because it only deals with the dependency injection system.

Fixtures everywhere !

Let's quickly implement the example I was just talking about: a READ endpoint that lists the existing items in the database :

    @app.get("/items/", response_model=List[schemas.Item])
    def read_items(db: Session = Depends(get_db)):
        return crud.get_items(db)

In order to test it we'd want to create a bunch of items before calling the endpoint, while having the database revert back to its original state after the test. The solution is simple : define our test database session in a fixture as well :

    # conftest.py

    @pytest.fixture(scope="session")
    def db_engine():
        engine = create_engine(SQLALCHEMY_DATABASE_URL)
        if not database_exists:
            create_database(engine.url)

        Base.metadata.create_all(bind=engine)
        yield engine


    @pytest.fixture(scope="function")
    def db(db_engine):
        connection = db_engine.connect()

        # begin a non-ORM transaction
        transaction = connection.begin()

        # bind an individual Session to the connection
        db = Session(bind=connection)
        # db = Session(db_engine)

        yield db

        db.rollback()
        connection.close()


    # 
    @pytest.fixture(scope="function")
    def client(db):
        app.dependency_overrides[get_db] = lambda: db

        with TestClient(app) as c:
            yield c

Pytest fixtures works like FastAPI dependencies: everything after the yield instruction is ran after exiting the scope pass as a paramter to the decorator. Our db fixture rollsback the session after each test, and we can use it to seed the database. I've also put the dependency override in a fixture alongside the client. That way each time we use the client, the override will be in place.

Now we can create the fixture we want and test our new endpoint :

    @pytest.fixture
    def items(db):
        create_item(db, schemas.ItemCreate(title="item 1"))
        create_item(db, schemas.ItemCreate(title="item 2"))

# test_database.py"
def test_list_items(items, client):
    response = client.get("/items")
    assert len(response.json()) == 2

And again our tests pass without issues no matter how many time we run them !

Hooray !

That's all folks !

That's it for today, now you know how to properly test you FastAPI app when using a relational database. Thanks for reading, I'll write another article on FastAPI soon !

References

1. FastAPI website
2. Testing relational database
3. SQLAlchemy docs
4. Transactions in SQLAlchemy