Published on

FastAPI Tutorial: Build Your First Python API in 10 Minutes

FastAPI is a modern Python framework that allows you to build a functional API (Application Programming Interface—a way for two software programs to communicate) in under 10 minutes. By using Python 3.12+ type hints, it automatically generates interactive documentation and validates your data, reducing code errors by up to 40% compared to older frameworks. You can launch your first "Hello World" endpoint with just five lines of code and a single terminal command.

What do you need to get started?

Before writing code, you need a few tools installed on your computer. We recommend using a code editor like VS Code and having a basic understanding of how to open a terminal or command prompt.

  • Python 3.12 or higher: This is the programming language FastAPI is built upon.
  • Pip: This is Python's package installer, which usually comes automatically when you install Python.
  • A Virtual Environment: This is a private folder for your project so its dependencies (external code libraries) don't mix with other projects.

To set up your workspace, create a new folder on your computer and open your terminal inside that folder. Run the command python -m venv venv to create your virtual environment, then activate it using source venv/bin/activate on Mac/Linux or venv\Scripts\activate on Windows.

How do you install FastAPI and Uvicorn?

FastAPI is the framework, but it needs a "server" to actually run your code on the internet or your local machine. We use Uvicorn (an ASGI server—a tool that handles many web requests at the same time) for this purpose.

Step 1: Ensure your virtual environment is active. You should see (venv) at the start of your terminal line.

Step 2: Run the following command to install the necessary packages:

pip install "fastapi[standard]"

Step 3: Wait for the installation to finish. This "standard" version includes Uvicorn and other helpful tools you'll need for development.

How do you write your first FastAPI code?

Now that the tools are ready, you can write the actual logic. Create a new file in your folder named main.py.

Step 4: Copy and paste the following code into main.py:

from fastapi import FastAPI # Import the FastAPI class

app = FastAPI() # Create an "instance" or copy of the framework to use

@app.get("/") # This tells FastAPI to listen for web requests at the home address
def read_root():
    # This function returns a simple Dictionary (a set of key-value pairs)
    return {"message": "Welcome to my first API!"}

@app.get("/items/{item_id}") # The curly braces indicate a "path parameter" (a variable)
def read_item(item_id: int):
    # This function takes the ID from the URL and returns it to the user
    return {"item_id": item_id, "status": "Found"}

How do you run the server and see the results?

Writing the code is only half the battle; you need to tell Python to start the web server so you can visit your API in a browser.

Step 5: In your terminal, run this command:

fastapi dev main.py

Step 6: Look for a line in the terminal that says Uvicorn running on http://127.0.0.1:8000. This address is your "localhost," meaning the website is running only on your computer for now.

Step 7: Open your web browser and go to http://127.0.0.1:8000. You should see the text {"message": "Welcome to my first API!"} on the screen.

Where is the automatic documentation?

One of the best parts of FastAPI is that it writes your manual for you. You don't have to spend hours explaining how your API works to other developers.

While your server is still running, go to http://127.0.0.1:8000/docs in your browser. You will see a clean, interactive page called Swagger UI.

This page lists every "endpoint" (a specific URL path) you created. You can click the "Try it out" button, enter an ID for the /items/{item_id} path, and click "Execute" to see the API respond in real-time.

Why does FastAPI use Type Hints?

In the code we wrote, you might have noticed item_id: int. This is a Type Hint (a way to tell Python what kind of data to expect).

In our experience, this is the most powerful feature for beginners because it catches mistakes before they happen. If you try to visit http://127.0.0.1:8000/items/apple, FastAPI will show an error message.

It does this because "apple" is a word (string), but you told the API to expect a whole number (integer). This automatic validation keeps your data clean and your app from crashing.

What are some common beginner gotchas?

It is normal to feel a bit confused when your code doesn't run the first time. Most errors come from small setup issues rather than logic mistakes.

  • Port already in use: If you see an error saying "address already in use," it means another program is using port 8000. You can stop it or try a different port.
  • ModuleNotFoundError: This usually means you forgot to activate your virtual environment. Always check for that (venv) prefix in your terminal.
  • Case Sensitivity: Python is picky about capital letters. Make sure app = FastAPI() uses a capital F and A, but lowercase app.

Don't worry if you have to restart your server a few times. The fastapi dev command actually watches your file for changes and restarts automatically whenever you save your code.

Next Steps

You have successfully built and documented a working API. To keep growing, try adding a new "POST" request to send data to your server instead of just reading it.

You might also explore Pydantic (a library for data validation) to define exactly how your data should look. This will help you build more complex applications like blog backends or task trackers.

For more detailed guides, visit the official Fastapi documentation.

Read the FastAPI Documentation