Getting Started with FastAPI : Creating the First REST API in 5 Minutes (FastAPI Quickstart)

martin blake 12월 15, 2025

A developer quickly building and testing their first REST API with FastAPI, showing both code and JSON responses.

Getting Started with FastAPI : Creating the First REST API in 5 Minutes (FastAPI Quickstart)

a summary at a glance

FastAPI is a modern, high-performance web framework for building APIs with Python 3.7+ based on standard type hints. In this first lesson, you will create a minimal project with a single main.py, add two endpoints (/health and /version), and run the app with uvicorn using the --reload option.

By the end of this tutorial, you will have: a working REST API, a simple Git repository with a README.md, and sample JSON responses that prove “my first API” is alive. The article is written for English-speaking beginners and working developers who are new to FastAPI.

Table of contents

Key takeaways

  • FastAPI focuses on speed and developer productivity. It uses Python type hints to validate data, generate documentation, and provide great editor support.
  • A minimal FastAPI API needs only a few lines of code. One main.py file is enough to expose working HTTP endpoints.
  • /health is a common endpoint to check if the service is alive. It usually returns a very small JSON like {"status": "ok"}.
  • /version helps clients know which version of your API or service they are calling. This is useful for debugging and compatibility checks.
  • uvicorn main:app --reload runs the app in development mode. The --reload flag automatically restarts the server when your code changes.
  • Putting your project in a Git repository from day one is a good habit. It makes it easier to share, roll back changes, and deploy later.

What is FastAPI and what will we build?

1. What is FastAPI?

FastAPI is a Python web framework designed specifically for building APIs quickly. It is built on top of modern ASGI (Asynchronous Server Gateway Interface) tools and supports both synchronous and asynchronous code. Its key strengths are:

  • High performance comparable to Node.js and Go in many scenarios.
  • Automatic interactive documentation via OpenAPI (Swagger UI and ReDoc).
  • First-class support for type hints, giving you validation and auto-completion.
  • Simple, readable syntax that feels familiar if you know standard Python.

2. What are we building in this first lesson?

In this “Hello, API” lesson, we intentionally keep things small and clear. We will:

  • Create a new project folder managed by Git.
  • Add a single main.py file that defines a FastAPI application.
  • Implement two endpoints:
    • GET /health – returns a simple JSON health check.
    • GET /version – returns the application name and version.
  • Run the app with uvicorn using --reload so that modifications are picked up automatically.
  • Open the browser or use curl to see your first JSON responses.

3. Why start with /health and /version?

These two endpoints are extremely common in real-world services. Operations teams and monitoring tools call /health to confirm that the application is up and responding. Clients and other services can call /version to log which version of the service they interacted with. Starting with these endpoints is a realistic first step toward production-ready APIs.

Step-by-step: build your first FastAPI app

  1. Create a project folder and initialize Git

    Choose a clean workspace and create a directory, for example: 

    # create project folder
mkdir fastapi-hello-api
cd fastapi-hello-api

# initialize Git repository

git init

    Initializing Git early makes it easy to track file changes and share your project on GitHub later.

  2. Set up Python and install FastAPI and Uvicorn

    Make sure you are using a recent Python 3 version (3.9 or later is recommended). Optionally, create and activate a virtual environment, then install the required packages: 

    # (optional) create and activate a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# install FastAPI and Uvicorn

pip install "fastapi[all]" "uvicorn[standard]"

    For a minimal setup you can also install fastapi and uvicorn[standard] only.

  3. Create main.py with the FastAPI application

    In the project root, create a file named main.py. This file will define the FastAPI application instance and the two endpoints. The full example code is provided in the “Code examples” section below.

  4. Run the application with uvicorn and --reload

    From the project root (where main.py lives), start the server: 

    # run FastAPI app with autoreload
uvicorn main:app --reload

    The pattern main:app means “import app from the main.py module.” By default, Uvicorn listens on http://127.0.0.1:8000. The --reload flag tells the server to automatically restart when you change Python files, which is ideal for development.

  5. Call /health and /version from your browser or terminal

    After the server starts, open these URLs in your browser:

    • http://127.0.0.1:8000/health
    • http://127.0.0.1:8000/version

    You should see JSON responses like: 

    {
  "status": "ok"
}

{
"name": "My First FastAPI Service",
"version": "1.0.0"
}

    These are your “my first API” screenshots in JSON form. You can also use curl to verify: 

    # health check
curl [http://127.0.0.1:8000/health](http://127.0.0.1:8000/health)

# version info

curl [http://127.0.0.1:8000/version](http://127.0.0.1:8000/version)
  6. Add a simple README.md for your Git repository

    Finally, create a README.md describing how to run the project. This is the minimum documentation you should include before pushing to GitHub. A sample is provided in the “Code examples” section. After creating it, commit your files: 

    git add main.py README.md
git commit -m "Add first FastAPI hello API"

Code examples

1. main.py: FastAPI app with /health and /version

# main.py
from fastapi import FastAPI

app = FastAPI(
title="My First FastAPI Service",
version="1.0.0",
)

@app.get("/health")
def health_check():
"""
Simple health check endpoint.

```
Returns a small JSON payload indicating that the service is alive.
"""
return {"status": "ok"}
```

@app.get("/version")
def version_info():
"""
Version information endpoint.

```
Exposes the application name and version so that clients and logs
can clearly identify which service build is running.
"""
return {
    "name": app.title,
    "version": app.version,
}
```

2. Running the server with uvicorn

# run the FastAPI app in development mode
uvicorn main:app --reload

# optional: specify host and port explicitly

uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. Suggested project structure (Git repo)

fastapi-hello-api/
├── main.py
├── README.md
└── .gitignore   # optional, e.g. ignore .venv, __pycache__, etc.

4. Example README.md

# FastAPI Hello API

This repository contains a minimal FastAPI project that exposes two endpoints:

* `GET /health` – simple health check.
* `GET /version` – returns service name and version.

## Requirements

* Python 3.9 or later
* pip

## Setup

```bash
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install "fastapi[all]" "uvicorn[standard]"
```

## Run

```bash
uvicorn main:app --reload
```

Open your browser at:

* [http://127.0.0.1:8000/health](http://127.0.0.1:8000/health)
* [http://127.0.0.1:8000/version](http://127.0.0.1:8000/version)

You should see JSON responses confirming that your first API is running.

```

Endpoint overview table

The table below summarizes the two endpoints implemented in this lesson, including their HTTP method, purpose, and a sample JSON response. You can reuse this style for future endpoints as your API grows.

Path HTTP method Description Typical use Sample JSON response
/health GET Checks if the API process is alive and responding. Used by monitoring tools, load balancers, and manual checks. {"status": "ok"}
/version GET Returns the service name and current version. Used for logging, debugging, and compatibility checks. {"name": "My First FastAPI Service", "version": "1.0.0"}

Something else to think about

  • Add automatic documentation next. FastAPI automatically generates interactive docs at /docs (Swagger UI) and /redoc. Exploring these should be your next step after confirming /health and /version.
  • Think about configuration management. Even for a small project, you may soon need environment-specific configuration (such as different versions or feature flags). Consider planning for this early.
  • Plan how to evolve your API. Once your first endpoints are stable, you might introduce versioned URLs (for example, /api/v1/) and more complex resources.
Reactions
martin blake

작성자: martin blake

댓글 쓰기

0 댓글