From 2222dc63a118263231eeb56bcd8d46f021a221fe Mon Sep 17 00:00:00 2001 From: RadinPirouz Date: Wed, 13 May 2026 17:03:08 +0330 Subject: [PATCH] updated simple route doc --- Docs/Libs/FastAPI/02-Simple-Route.md | 257 +++++++++++++++++++++++---- 1 file changed, 219 insertions(+), 38 deletions(-) diff --git a/Docs/Libs/FastAPI/02-Simple-Route.md b/Docs/Libs/FastAPI/02-Simple-Route.md index 22abfbd..6cdb686 100644 --- a/Docs/Libs/FastAPI/02-Simple-Route.md +++ b/Docs/Libs/FastAPI/02-Simple-Route.md @@ -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 +```