FastAPI Local Guide

Overview

FastAPI is a modern Python web framework for building APIs quickly, with support for data validation using Python type hints. In this guide, we'll walk you through setting up and running a FastAPI server locally using Uvicorn, an ASGI server.

1. Installation

To begin with FastAPI, you need to install it along with Uvicorn, which serves as the server to run FastAPI applications.

Installation Command:

pip install fastapi uvicorn

2. Creating the FastAPI Server

Once the dependencies are installed, create a FastAPI application with Python. Typically, your main application will have API endpoints defined using decorators like @app.get(), @app.post(), etc.

3. Running the Server Locally

To run the FastAPI application, you will use Uvicorn. Uvicorn runs the FastAPI application on an ASGI server.

Starting the FastAPI Server:

cd src
poetry shell
poetry run python api/run_app_schemas.py --host 0.0.0.0 --port 8000 --reload
poetry run python api/run_app_hunts.py --host 0.0.0.0 --port 8001 --reload

• main: Refers to the main.py file.

• app: Refers to the FastAPI instance in your file.

• --reload: Automatically reloads the server on code changes (useful during development).

Accessing the Server:

Once the server is running, it will be available at http://127.0.0.1:8000 by default. You can visit this URL in a browser or API client to interact with your endpoints.

4. Accessing the API

When running a FastAPI application, you can access your API's automatically generated documentation through these URLs:

• Swagger UI (interactive API docs): http://127.0.0.1:8000/docs or http://127.0.0.1:8001/docs

• ReDoc (alternative documentation UI): http://127.0.0.1:8000/redoc or http://127.0.0.1:8001/redoc

These tools make it easy to test and document your API.

5. Testing the API

You can test your API using API tools like Postman or cURL. Once the server is running, you can send requests to the endpoints defined in your FastAPI app.

Example Request with cURL:

curl --include --request GET "http://localhost:8000/health"
curl --include --request GET "http://localhost:8000/health?target_name=integration&targets_file_path=~/.xdr/xdr_targets.yaml"
curl -X POST "http://127.0.0.1:8000/your-endpoint/" -H "Content-Type: application/json" -d '{"param1": "value1"}'
curl -X POST "http://127.0.0.1:8000/your-endpoint/" -H "Content-Type: application/json" -d '{}'

Or, use Postman to send requests and view responses.

6. FastAPI Request Flow Diagram

Below is a high-level diagram illustrating how requests flow through a FastAPI application using Uvicorn as the server:

+-------------+          +------------------+          +--------------------+
|             |          |                  |          |                    |
|  User/API   +--------->+  FastAPI Router   +--------->+ FastAPI Endpoints |
|   Client    |          | (Request Routing)|          |  (Business Logic)  |
|             |          |                  |          |                    |
+-------------+          +------------------+          +--------------------+
                                 |
                                 v
                          +---------------+
                          |  Uvicorn ASGI  |
                          |  Server Layer  |
                          +---------------+
                                 |
                                 v
                          +---------------+
                          | Python Backend|
                          +---------------+

7. Docker Setup

Running Docker Containers

1. Build the containers:

   cd fastapi_devcontainer
   docker-compose down --volumes --remove-orphans
   docker-compose build or docker-copose build --no-cache
   docker-compose up

2. Down the containers if issues arise:

   docker-compose down --volumes --remove-orphans
   docker container rm -f api_schemas api_hunts api_clickhouse
   docker container prune

8. Prometheus Scraping

To scrape metrics from your FastAPI application using Prometheus:

Configure Prometheus

In your prometheus.yml, you need to specify the FastAPI applications as scrape targets:

scrape_configs:
  - job_name: 'fastapi-schemas'
    static_configs:
      - targets: ['schemas:8000']

  - job_name: 'fastapi-hunts'
    static_configs:
      - targets: ['hunts:8001']

Expose Metrics in FastAPI

To expose metrics, modify your FastAPI applications:

from prometheus_fastapi_instrumentator import Instrumentator

instrumentator = Instrumentator()
instrumentator.instrument(app).expose(app)

Accessing Prometheus Metrics

Once Prometheus is running, you can access its web UI at http://localhost:9090 and check the metrics collected from your FastAPI applications.