radin/python-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated simple route doc

Browse Source
This commit is contained in:
RadinPirouz
2026-05-13 17:03:08 +03:30
parent 7c08e19545
commit 2222dc63a1
1 changed files with 219 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
Docs/Libs/FastAPI/02-Simple-Route.md
View File

@@ -1,12 +1,22 @@
# FastAPI – Simple Route Example
This document demonstrates how to create a basic FastAPI application with a single HTTP route and how to run it using `uvicorn`, which is the default and recommended ASGI server for FastAPI.
## 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.
---
## Create a Simple FastAPI Application
# 1. Create a Simple FastAPI Application
Create a Python file named `main.py` and add the following content:
Create a Python file named:
```text
main.py
```
Add the following code:
```python
from fastapi import FastAPI
@@ -19,72 +29,243 @@ def home_dir():
return {"message": "Home Page"}
```
### Explanation
---
* `FastAPI()` initializes the application instance.
* `@app.get("/")` registers an HTTP GET endpoint at the root path (`/`).
* The `home_dir` function is the request handler and returns a JSON response.
* FastAPI automatically handles JSON serialization and response headers.
# 2. Code Explanation
## Import FastAPI
```python
from fastapi import FastAPI
```
This imports the `FastAPI` class from the FastAPI package.
---
## Running the Application
## Create the Application Instance
FastAPI applications are typically run using **uvicorn**, an ASGI server designed for high performance.
```python
app = FastAPI()
```
### Option 1: Run Using FastAPI CLI (Development Mode)
This creates the main FastAPI application instance.
FastAPI provides a development-friendly CLI wrapper that uses `uvicorn` internally:
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:
This command starts the FastAPI application in development mode.
* Starts the application in development mode
* Enables auto-reload on code changes
* Automatically binds to a local development interface
It is useful during local development because it supports automatic reload when the source code changes.
---
### Option 2: Run Directly with Uvicorn (Recommended)
## Option 2: Run Directly with Uvicorn
For explicit control over runtime configuration, run the application directly with `uvicorn`:
You can also run the application directly using `uvicorn`:
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 1234
```
#### Command Breakdown
* `main` → Python file name (without `.py`)
* `app` → FastAPI application instance
* `--reload` → Automatically reloads the server on code changes (development only)
* `--host 0.0.0.0` → Exposes the service on all network interfaces
* `--port 1234` → Custom application port
This is the more explicit and commonly used method.
---
## Accessing the Application
# 4. Uvicorn Command Breakdown
Once running, the application will be available at:
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 1234
```
* API Endpoint:
`http://localhost:1234/`
## `uvicorn`
* Interactive API Docs (Swagger UI):
`http://localhost:1234/docs`
Starts the ASGI server.
* Alternative API Docs (ReDoc):
`http://localhost:1234/redoc`
## `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`.
---
## Best Practices
# 5. Accessing the Application
* Use `--reload` only in development environments
* In production, run `uvicorn` behind a process manager (e.g., systemd, Docker, Kubernetes)
* Explicitly define host and port for containerized and cloud deployments
* Keep the application entry point (`main:app`) consistent across environments
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
```