Build A Basic FastAPI Service: A Step-by-Step Guide

Oct 19, 2025 by SLV Team 52 views

Hey guys! Let's dive into building a basic API service using FastAPI. This guide will walk you through the process of setting up endpoints, wiring everything together, and containerizing your application with Docker. By the end, you'll have a fully functional API that you can deploy and use.

Understanding the Basics of FastAPI

Before we jump into the code, let's quickly talk about FastAPI. FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints. One of the key advantages of FastAPI is its speed. It’s designed to be highly performant, competing with Node.js and Go in terms of raw speed. This makes it an excellent choice for building APIs that need to handle a lot of requests. Another advantage of FastAPI is its ease of use. It's designed to be intuitive and easy to learn, even for developers who are new to building APIs. This is partly thanks to its use of Python type hints, which make it easier to define and validate data structures. FastAPI also comes with automatic data validation and serialization. This means you don't have to write a lot of boilerplate code to ensure that your API is handling data correctly. FastAPI uses Pydantic for data validation, which is a popular and powerful library for defining data models in Python. Moreover, FastAPI automatically generates API documentation using OpenAPI and JSON Schema standards. This means you get interactive API documentation out of the box, which can be a huge time-saver. You can easily test your API endpoints directly from the browser, which makes development and debugging much easier. To sum up, FastAPI is a great choice for building APIs because it's fast, easy to use, and comes with a lot of features that can save you time and effort. Whether you're building a small personal project or a large-scale application, FastAPI has you covered. Now, let's get our hands dirty and start building our basic API service!

Project Setup and File Structure

Okay, let’s get our hands dirty and start setting up our project. First things first, we need to create a directory for our project. Think of this as the main hub for all our code and related files. You can name it something like basic-fastapi-service or anything that tickles your fancy. The name isn't too important as long as it’s descriptive enough for you to remember what it’s for. Once you’ve created the main directory, we'll need to set up a specific file structure inside it. This structure will help keep our project organized and make it easier to find things later on. We’re going to create three main components: a Dockerfile, api/requirements.txt, and an api directory containing our FastAPI application. Inside the api directory, we'll have an app subdirectory, which will house our main application files: main.py and routes.py. So, our file structure will look something like this:

basic-fastapi-service/
├── api/
│   ├── Dockerfile
│   ├── requirements.txt
│   │   └── app/
│   │       ├── main.py
│   │       └── routes.py

Let's break down why we're setting things up this way. The Dockerfile is crucial for containerizing our application using Docker. It contains the instructions needed to build a Docker image, which we can then use to run our API in a container. The requirements.txt file lists all the Python packages our project depends on. This makes it easy to install all the necessary dependencies at once, ensuring that our application runs correctly in different environments. Inside the api directory, the app subdirectory holds our core application logic. main.py will be the entry point of our application, where we’ll initialize the FastAPI app and configure any necessary settings. routes.py will contain our API endpoints, defining the different URLs that our API will respond to. Having a clear file structure like this is super important for maintaining a clean and organized codebase. It makes it easier to navigate the project, understand the different components, and collaborate with others. Now that we have our file structure in place, let's move on to the next step: creating the Dockerfile.

Creating the Dockerfile

Alright, let's dive into creating our Dockerfile. This file is like a blueprint for building our Docker image, which we'll use to containerize our FastAPI application. Think of it as a set of instructions that tells Docker exactly how to set up our environment. We'll start by specifying the base image. This is the foundation upon which our container will be built. For a Python application like ours, it's common to use an official Python image from Docker Hub. We'll use the python:3.9-slim-buster image, which is a lightweight version that includes Python 3.9 and the necessary dependencies for running Python applications. Next, we need to set the working directory inside the container. This is the directory where our application code will live. We'll set it to /app, which is a common convention. Then, we'll copy our requirements.txt file into the container and install the dependencies using pip. This ensures that all the necessary Python packages are installed before we copy our application code. After that, we'll copy our application code into the container. This includes the api directory and all its contents, including main.py and routes.py. Finally, we'll specify the command to run when the container starts. For a FastAPI application, this typically involves using uvicorn, an ASGI server that's designed to be fast and efficient. We'll use the command uvicorn api.app.main:app --host 0.0.0.0 --port 8000, which tells uvicorn to run our FastAPI application (app from api/app/main.py) on all available network interfaces (0.0.0.0) and port 8000. Here’s what the Dockerfile will look like:

FROM python:3.9-slim-buster

WORKDIR /app

COPY api/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY api .

CMD ["uvicorn", "api.app.main:app", "--host", "0.0.0.0", "--port", "8000"]

This Dockerfile is relatively simple, but it does everything we need to containerize our FastAPI application. It sets up the environment, installs the dependencies, copies the code, and specifies the command to run. Now that we have our Dockerfile, we can move on to creating the requirements.txt file.

Setting up `requirements.txt`

Now, let's get to setting up the requirements.txt file. This little guy is super important because it tells our application which Python packages it needs to run smoothly. Think of it as a shopping list for our project's dependencies. We need to include FastAPI and Uvicorn, which is our ASGI server. FastAPI is the star of the show – it's the web framework we're using to build our API. And Uvicorn? Well, it's the super-fast server that will run our FastAPI app. To keep things clean and efficient, it's a good idea to specify the versions of these packages. This helps ensure that our application behaves consistently across different environments. So, our requirements.txt file should look something like this:

fastapi==0.100.0
uvicorn[standard]==0.23.0

Why these specific versions, you ask? Well, it's always a good practice to pin your dependencies to specific versions to avoid unexpected issues when new versions are released. This way, you have more control over your application's behavior. You can always update the versions later, but starting with specific versions gives you a stable foundation. Now that we have our requirements.txt file ready, let's jump into building the actual FastAPI application. We'll start by setting up the main application file, main.py.

Building the FastAPI Application (`main.py`)

Alright, let's start building the heart of our application – the main.py file. This is where we'll initialize our FastAPI app and set up the basic structure. First things first, we need to import the FastAPI class from the fastapi library. This class is what we'll use to create our application instance. Next, we'll create an instance of the FastAPI class. This is our main application object, and we'll use it to define our API endpoints and other settings. We'll name our instance app, which is a common convention. Now, let's set up a basic route. A route is a URL path that our API will respond to. For example, we can create a route that responds to the root path (/) and returns a simple message. To define a route, we use the @app.get() decorator. This decorator tells FastAPI that the function below it should be called when a GET request is made to the specified path. Inside the function, we can return a dictionary or a Pydantic model, and FastAPI will automatically serialize it to JSON. For our basic route, we'll return a simple dictionary with a message. Here’s what our main.py file will look like:

from fastapi import FastAPI

app = FastAPI()

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

In this code, we've imported the FastAPI class, created an instance of it, and defined a route that responds to the root path. When a user visits the root path of our API, they'll see the message "Hello World from FastAPI!". This is a simple example, but it shows the basic structure of a FastAPI application. Now, let's move on to defining more complex routes in our routes.py file.

Defining API Endpoints (`routes.py`)

Now, let's move on to defining our API endpoints in the routes.py file. This is where we'll create the specific URLs that our API will respond to and define the logic for handling requests to those endpoints. To keep things organized, it's a good practice to separate our routes into different files or modules. This makes it easier to manage our application as it grows. In our case, we'll create a routes.py file in the api/app directory and define our endpoints there. First, we need to import the APIRouter class from the fastapi library. This class allows us to create a set of routes that can be included in our main application. We'll create an instance of the APIRouter class, which we can then use to define our endpoints. Let's define a simple endpoint that returns a list of items. We'll create a route at /items that responds to GET requests and returns a list of dictionaries, each representing an item. To define this route, we use the @router.get() decorator, just like we used @app.get() in main.py. Inside the function, we can return a list of dictionaries, and FastAPI will automatically serialize it to JSON. Here’s an example of what our routes.py file might look like:

from fastapi import APIRouter

router = APIRouter()

@router.get("/items")
async def read_items():
    items = [
        {"name": "Item 1", "description": "This is item 1"},
        {"name": "Item 2", "description": "This is item 2"},
    ]
    return items

In this code, we've imported the APIRouter class, created an instance of it, and defined a route that responds to GET requests at /items. When a user visits this endpoint, they'll see a list of items in JSON format. Now, we need to include these routes in our main application. To do this, we'll go back to our main.py file and import the router from routes.py. We'll then use the app.include_router() method to include the routes in our main application. Here’s how we can modify our main.py file to include the routes:

from fastapi import FastAPI
from .app import routes

app = FastAPI()

app.include_router(routes.router)

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

In this code, we've imported the routes module and included the router in our main application. This means that all the routes defined in routes.py will now be part of our API. Now that we've defined our API endpoints, let's move on to testing our application.

Running and Testing the API

Alright, guys, we've got our FastAPI application all set up, and now it's time for the fun part – running and testing it! First off, let's build our Docker image. Open up your terminal, navigate to the root directory of your project (where the Dockerfile is), and run this command:

docker build -t basic-fastapi-api .

This command tells Docker to build an image using the Dockerfile in the current directory (.). The -t flag lets us tag the image with a name, in this case, basic-fastapi-api. This makes it easier to refer to the image later on. Docker will go through the instructions in the Dockerfile, setting up the environment, installing dependencies, and copying our code into the image. Once the image is built, we can run it in a container. Use this command:

docker run -p 8000:8000 basic-fastapi-api

Here, docker run creates and starts a container from our image. The -p 8000:8000 flag maps port 8000 on our host machine to port 8000 in the container. This means we can access our API by visiting http://localhost:8000 in our browser. Now, let's test our API. FastAPI comes with automatic API documentation generated using OpenAPI, which is super handy for testing our endpoints. To access the documentation, just add /docs to the end of your API's URL. So, in our case, we'll visit http://localhost:8000/docs. You should see a Swagger UI page that lists all our API endpoints. You can click on each endpoint to see its details, including the request parameters and response schema. You can also try out the endpoints directly from the Swagger UI page, which makes testing a breeze. To test our root endpoint, we can simply visit http://localhost:8000 in our browser. You should see the message "Hello World from FastAPI!" in JSON format. To test our /items endpoint, we can visit http://localhost:8000/items. You should see the list of items we defined in our routes.py file, also in JSON format. If everything is working as expected, congratulations! You've successfully built and tested a basic FastAPI API. If you encounter any issues, double-check your code, Dockerfile, and dependencies. Make sure everything is set up correctly, and don't hesitate to consult the FastAPI documentation or online resources for help.

Acceptance Criteria: `/api/docs` Responds

Okay, let's talk about our acceptance criteria. The main goal here is to make sure that when we spin up our container, the /api/docs endpoint responds correctly. This is crucial because it means our automatic API documentation is being generated and served as expected. To verify this, we'll follow these steps: First, we'll build our Docker image using the docker build command, just like we discussed earlier. Then, we'll run the image in a container using the docker run command, making sure to map port 8000 on our host machine to port 8000 in the container. Once the container is running, we'll open a web browser and navigate to http://localhost:8000/docs. This is where our API documentation should be served. If everything is set up correctly, we should see the Swagger UI page, which lists all our API endpoints and allows us to interact with them. If we see the Swagger UI page, it means our /api/docs endpoint is responding as expected, and we've met our acceptance criteria. If, for some reason, we don't see the Swagger UI page, we'll need to troubleshoot the issue. This might involve checking our FastAPI configuration, making sure we've included the necessary middleware for serving the documentation, and verifying that our Docker container is running correctly. Meeting this acceptance criteria is super important because it ensures that we have a way to easily test and document our API. Automatic API documentation is one of the key features of FastAPI, and it makes it much easier to develop and maintain our API over time. So, let's make sure we get this right!

Conclusion

Alright, folks! We've reached the end of our journey in building a basic FastAPI service and containerizing it with Docker. We've covered a lot of ground, from setting up our project structure to defining API endpoints and ensuring our documentation is in tip-top shape. We kicked things off by understanding the fundamentals of FastAPI and why it's a fantastic choice for building APIs. We then moved on to setting up our project, creating the necessary file structure, and diving into the Dockerfile to containerize our application. We also tackled the requirements.txt file, making sure we had all the necessary dependencies in place. From there, we built the heart of our application in main.py, defined our API endpoints in routes.py, and learned how to run and test our API. Finally, we made sure we met our acceptance criteria by verifying that the /api/docs endpoint was responding correctly. By following this guide, you've gained a solid foundation in building FastAPI applications and containerizing them with Docker. You now have the tools and knowledge to create your own APIs and deploy them in a consistent and reliable manner. Remember, building APIs is an iterative process. Don't be afraid to experiment, try new things, and continuously improve your code. The more you practice, the better you'll become. So, keep coding, keep building, and keep pushing the boundaries of what's possible. Happy coding, guys!