Building Your First FastAPI App with Uvicorn

1. Anatomy of a Minimal FastAPI App

Let's revisit the code from our main.py file. It's concise, but every line serves a distinct purpose.

# main.py

from fastapi import FastAPI

app = FastAPI()

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

Since you're comfortable with Python decorators, the @app.get("/") syntax might already look familiar. It's the heart of how FastAPI connects a URL to your code. To get an authoritative breakdown of this structure, the official FastAPI documentation is the best place to turn.

As you've just read, we can summarize the structure into four main parts:

1. from fastapi import FastAPI: We import the necessary class from the library. This FastAPI class provides all the core functionality.
2. app = FastAPI(): We create an instance of the FastAPI class. This app object is the main point of interaction for creating all the parts of your API.
3. @app.get("/"): This is a path operation decorator. It tells FastAPI that the function directly below it is responsible for handling requests that go to the path / using a GET operation.
4. def read_root(): ...: This is the path operation function. It's a standard Python function that FastAPI calls whenever it receives a matching request. The value returned by this function is sent back to the client as the body of the HTTP response.

2. Path, Operation, and Function

Let's focus on the most critical part: the connection between the decorator and the function.

@app.get("/")

• Path: The path is the part of the URL that comes after the domain. In this case, "/" refers to the root of your site (e.g., http://127.0.0.1:8000/). If you were to use "/items/", the full URL would be http://127.0.0.1:8000/items/.
• Operation: The operation refers to the HTTP method. get is used for reading data. FastAPI provides decorators for all standard HTTP methods, such as @app.post(), @app.put(), and @app.delete(), which we will use in later lessons.

def read_root(): return {"message": "Hello World"}

This function is executed when a GET request to / is received. Notice that it returns a standard Python dictionary. FastAPI automatically handles the conversion of this dictionary (and many other data types) into a JSON response. This is a powerful feature that simplifies development, as you don't need to manually serialize your data.

You'll also see that the function is defined with def. Given your experience with async/await, you'll be glad to know that FastAPI works seamlessly with both standard synchronous functions (def) and asynchronous ones (async def). We'll explore the implications of this choice in more detail later, but for simple, non-I/O-bound operations like this, a standard def is perfectly fine.

3. Running the Server with Uvicorn

In the previous lesson, you ran uvicorn main:app --reload to start the server. Now that you understand the components inside main.py, that command should make more sense.

• uvicorn: The ASGI server program.
• main:app: This tells Uvicorn where to find the application instance. It follows the format <module_name>:<instance_name>. So, it looks in the main.py file (the main module) for the variable named app.
• --reload: This development-friendly flag tells Uvicorn to monitor your project files for changes and automatically restart the server when you save a file. This gives you a very fast feedback loop.

The following video provides a great demonstration of this process and introduces an alternative command you can also use.

Your Turn: Hands-On Practice

Let's put this knowledge into practice.

1. Open your terminal in the project directory.
2. Make sure your virtual environment is activated.
3. Run the server: uvicorn main:app --reload
4. Open your browser and navigate to http://127.0.0.1:8000. You should see {"message":"Hello World"}.
5. Now, go back to your main.py file in your code editor.
6. Change the return value of the read_root function to something different. For example: return {"status": "ok", "version": "1.0"}.
7. Save the file.
8. Look at your terminal. You should see Uvicorn detect the change and restart the server.
9. Go back to your browser and refresh the page at http://127.0.0.1:8000. You will now see your new JSON response.

This simple exercise demonstrates the entire development cycle: writing code, running the server, and testing the result.

Conclusion

In this lesson, we moved from simply running code to understanding it. You've dissected a minimal FastAPI application and now have a clear mental model of how it works.

Here are the key takeaways:

• An endpoint in FastAPI is a combination of a path operation decorator (like @app.get("/")) and a path operation function that handles the request.
• FastAPI automatically converts Python data structures like dictionaries into JSON responses.
• The uvicorn main:app --reload command is your primary tool for running the server during development, providing a fast and efficient workflow with its auto-reloading capability.

You've now mastered the fundamental building block of any FastAPI application. With this foundation, we can start exploring more powerful features.

In the next lesson, we will look at one of FastAPI's most celebrated features: the automatic interactive API documentation (Swagger UI). You'll learn how to use this tool to test your endpoints directly in the browser, a skill that will dramatically accelerate your development and testing process.