272 lines
4.3 KiB
Markdown
272 lines
4.3 KiB
Markdown
# FastAPI – Simple Route Example
|
||
|
||
## Overview
|
||
|
||
This document explains how to create a basic FastAPI application with a single HTTP route and how to run it using `uvicorn`.
|
||
|
||
FastAPI is an ASGI web framework, and `uvicorn` is commonly used as the ASGI server to run FastAPI applications.
|
||
|
||
---
|
||
|
||
# 1. Create a Simple FastAPI Application
|
||
|
||
Create a Python file named:
|
||
|
||
```text
|
||
main.py
|
||
```
|
||
|
||
Add the following code:
|
||
|
||
```python
|
||
from fastapi import FastAPI
|
||
|
||
app = FastAPI()
|
||
|
||
|
||
@app.get("/")
|
||
def home_dir():
|
||
return {"message": "Home Page"}
|
||
```
|
||
|
||
---
|
||
|
||
# 2. Code Explanation
|
||
|
||
## Import FastAPI
|
||
|
||
```python
|
||
from fastapi import FastAPI
|
||
```
|
||
|
||
This imports the `FastAPI` class from the FastAPI package.
|
||
|
||
---
|
||
|
||
## Create the Application Instance
|
||
|
||
```python
|
||
app = FastAPI()
|
||
```
|
||
|
||
This creates the main FastAPI application instance.
|
||
|
||
The variable name `app` is important because it is later used by `uvicorn` when starting the server.
|
||
|
||
---
|
||
|
||
## Define a GET Route
|
||
|
||
```python
|
||
@app.get("/")
|
||
def home_dir():
|
||
return {"message": "Home Page"}
|
||
```
|
||
|
||
This creates an HTTP `GET` endpoint at the root path:
|
||
|
||
```http
|
||
GET /
|
||
```
|
||
|
||
When a user sends a request to `/`, the `home_dir` function is executed.
|
||
|
||
The function returns a Python dictionary:
|
||
|
||
```python
|
||
{"message": "Home Page"}
|
||
```
|
||
|
||
FastAPI automatically converts this dictionary into a JSON response.
|
||
|
||
---
|
||
|
||
# 3. Running the Application
|
||
|
||
FastAPI applications are usually run using `uvicorn`.
|
||
|
||
---
|
||
|
||
## Option 1: Run Using FastAPI CLI
|
||
|
||
You can run the application in development mode using:
|
||
|
||
```bash
|
||
fastapi dev main.py
|
||
```
|
||
|
||
This command starts the FastAPI application in development mode.
|
||
|
||
It is useful during local development because it supports automatic reload when the source code changes.
|
||
|
||
---
|
||
|
||
## Option 2: Run Directly with Uvicorn
|
||
|
||
You can also run the application directly using `uvicorn`:
|
||
|
||
```bash
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 1234
|
||
```
|
||
|
||
This is the more explicit and commonly used method.
|
||
|
||
---
|
||
|
||
# 4. Uvicorn Command Breakdown
|
||
|
||
```bash
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 1234
|
||
```
|
||
|
||
## `uvicorn`
|
||
|
||
Starts the ASGI server.
|
||
|
||
## `main`
|
||
|
||
Refers to the Python file name:
|
||
|
||
```text
|
||
main.py
|
||
```
|
||
|
||
You write `main`, not `main.py`.
|
||
|
||
## `app`
|
||
|
||
Refers to the FastAPI application instance:
|
||
|
||
```python
|
||
app = FastAPI()
|
||
```
|
||
|
||
## `--reload`
|
||
|
||
Automatically restarts the server when code changes.
|
||
|
||
This should only be used in development.
|
||
|
||
## `--host 0.0.0.0`
|
||
|
||
Makes the application listen on all available network interfaces.
|
||
|
||
This is useful when running inside Docker, virtual machines, or remote servers.
|
||
|
||
## `--port 1234`
|
||
|
||
Runs the application on port `1234`.
|
||
|
||
---
|
||
|
||
# 5. Accessing the Application
|
||
|
||
After starting the server, the application will be available at:
|
||
|
||
```text
|
||
http://localhost:1234/
|
||
```
|
||
|
||
The response will be:
|
||
|
||
```json
|
||
{
|
||
"message": "Home Page"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 6. Interactive API Documentation
|
||
|
||
FastAPI automatically generates API documentation.
|
||
|
||
## Swagger UI
|
||
|
||
```text
|
||
http://localhost:1234/docs
|
||
```
|
||
|
||
Swagger UI allows you to test API endpoints directly from the browser.
|
||
|
||
## ReDoc
|
||
|
||
```text
|
||
http://localhost:1234/redoc
|
||
```
|
||
|
||
ReDoc provides a clean documentation view for the API.
|
||
|
||
---
|
||
|
||
# 7. Complete Example
|
||
|
||
```python
|
||
from fastapi import FastAPI
|
||
|
||
app = FastAPI()
|
||
|
||
|
||
@app.get("/")
|
||
def home_dir():
|
||
return {"message": "Home Page"}
|
||
```
|
||
|
||
Run it with:
|
||
|
||
```bash
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 1234
|
||
```
|
||
|
||
---
|
||
|
||
# 8. Best Practices
|
||
|
||
Use `--reload` only during development.
|
||
|
||
Use a consistent application entry point such as:
|
||
|
||
```text
|
||
main:app
|
||
```
|
||
|
||
Explicitly define the host and port in Docker, cloud, or server environments.
|
||
|
||
Use `0.0.0.0` when the application needs to be reachable from outside the local machine.
|
||
|
||
Use `127.0.0.1` or `localhost` when the application should only be accessible locally.
|
||
|
||
Do not expose development servers directly to the internet.
|
||
|
||
In production, run FastAPI behind a proper process manager, reverse proxy, or container orchestration platform.
|
||
|
||
---
|
||
|
||
# 9. DevOps Production Note
|
||
|
||
The following command is suitable for local development:
|
||
|
||
```bash
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 1234
|
||
```
|
||
|
||
For production, avoid using `--reload`.
|
||
|
||
A typical production setup may include:
|
||
|
||
```text
|
||
FastAPI
|
||
Uvicorn or Gunicorn with Uvicorn workers
|
||
Nginx or Traefik
|
||
Docker or Kubernetes
|
||
Logging and monitoring
|
||
Health checks
|
||
Environment-based configuration
|
||
```
|
||
|
||
Example production-style command:
|
||
|
||
```bash
|
||
uvicorn main:app --host 0.0.0.0 --port 1234
|
||
```
|