Home Original page

GitHub - documentdb/fast-api-sample

FastAPI + DocumentDB E-Commerce Demo

A modern, full-stack e-commerce application built with FastAPI and open-source DocumentDB (MongoDB-compatible), orchestrated with Docker containers.

🧪 New to this project? Start here for step-by-step instructions!

🎯 What You'll Learn

  • Setting up a FastAPI backend and connecting it to DocumentDB using Docker Compose
  • How open-source DocumentDB enables rapid iteration and seamless migration to cloud environments
  • Using the DocumentDB for VS Code extension to explore, query, and manage your database visually

🏗️ Architecture

  • Backend: FastAPI (Python 3.11+)
  • Database: DocumentDB (MongoDB-compatible, PostgreSQL-based)
  • ODM: Beanie (async MongoDB ODM built on Pydantic)
  • Containerization: Docker & Docker Compose
  • Developer Tools: DocumentDB for VS Code extension, MongoDB Playground

📋 Prerequisites

  • Docker Desktop installed and running
  • Python 3.11+ (for local development)
  • Git
  • VS Code with DocumentDB extension (recommended)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/documentdb/fast-api-sample.git
cd fast-api-sample

2. Set up your DocumentDB instance

# Pull the latest DocumentDB Docker image
docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest

# Tag the image for convenience
docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb

# Run the container with your chosen username and password
docker run -dt -p 10260:10260 --name documentdb-container documentdb --username <YOUR_USERNAME> --password <YOUR_PASSWORD>
docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest
  • Click the DocumentDB icon in the VS Code sidebar
  • Click "Add New Connection"
  • On the navigation bar, click on "Connection String"
  • Paste your connection string
mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256
  • Click on the drop-down next to your local connection and select "Create Database..."
  • Enter database name and confirm (suggested: ecommerce)
  • Click on the drop-down next to your created database and select "Create Collection..."
  • Create your collections, products and customers and confirm.

3. Import data to DocumentDB

  • For each collection, click the Import button on the top-right corner.
  • Import the /scripts/sample_customers.json file in the customers collection and /scripts/sample_products.json file in the products collection.

4. Set Up Environment Variables

In the .env file, add your connection string, database name, and DocumentDB credentials.

Afterwards, install the requirements needed for the data to migrate to the frontend.

cd backend
pip install -r requirements.txt

5. Start the Application

This will:

  • Build the FastAPI backend container
  • Pull and start the DocumentDB container
  • Set up networking between services
  • Initialize the database connection

6. Access the Application

📚 API Endpoints

Products

  • GET /api/v1/products - List all products (with pagination)
  • GET /api/v1/products/{id} - Get a specific product
  • POST /api/v1/products - Create a new product
  • PUT /api/v1/products/{id} - Update a product
  • DELETE /api/v1/products/{id} - Delete a product

Orders

  • GET /api/v1/orders - List all orders
  • GET /api/v1/orders/{id} - Get a specific order
  • POST /api/v1/orders - Create a new order
  • PUT /api/v1/orders/{id}/status - Update order status

Customers

  • GET /api/v1/customers - List all customers
  • GET /api/v1/customers/{id} - Get a specific customer
  • POST /api/v1/customers - Create a new customer

🧪 Running Tests

# Run all tests
docker-compose exec backend pytest

# Run with coverage
docker-compose exec backend pytest --cov=app --cov-report=html

# Run specific test file
docker-compose exec backend pytest tests/test_products.py

🛠️ Development Workflow

Using the DocumentDB for VS Code Extension (Recommended)

The DocumentDB for VS Code extension provides a powerful, integrated way to explore and manage your database directly within VS Code.

Quick Setup

  1. Install the Extension:

    • Open VS Code Extensions (Ctrl+Shift+X / Cmd+Shift+X)
    • Search for "DocumentDB for VS Code"
    • Install the extension by Microsoft (ms-azuretools.vscode-documentdb)

  2. Connect to Your Local Database:

    • Click the DocumentDB icon in the Activity Bar
    • Click "Add New Connection" → "Connection String"
    • Paste: mongodb://docdb_user:docdb_password@localhost:27017/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256
    • Name it "E-commerce Local Dev" and connect

  3. Explore Your Data:

    • Expand your connection to see databases and collections
    • View documents in Table, Tree, or JSON view
    • Run queries with IntelliSense support
    • Import/Export data as JSON

📖 Detailed Guide: See DocumentDB Extension Guide for comprehensive documentation.

Alternative: Command Line Access

Connect to DocumentDB using mongosh:

mongosh localhost:27017 -u docdb_user -p docdb_password \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls --tlsAllowInvalidCertificates

Local Development (without Docker)

  1. Install dependencies:
cd backend
pip install -r requirements.txt
  1. Start DocumentDB separately:
docker run -dt -p 27017:27017 \
  --name documentdb-local \
  ghcr.io/microsoft/documentdb/documentdb-local:latest \
  --username docdb_user --password docdb_password
  1. Run the FastAPI app:
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f documentdb

Rebuild After Code Changes

docker-compose down
docker-compose up --build

📁 Project Structure

.
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI application entry point
│   │   ├── core/
│   │   │   ├── config.py        # Configuration settings
│   │   │   └── database.py      # Database connection setup
│   │   ├── models/              # Beanie document models
│   │   │   ├── product.py
│   │   │   ├── order.py
│   │   │   └── customer.py
│   │   ├── routers/             # API route handlers
│   │   │   ├── products.py
│   │   │   ├── orders.py
│   │   │   └── customers.py
│   │   └── schemas/             # Pydantic request/response schemas
│   │       ├── product.py
│   │       ├── order.py
│   │       └── customer.py
│   ├── tests/                   # Test files
│   │   ├── conftest.py
│   │   ├── test_products.py
│   │   ├── test_orders.py
│   │   └── test_customers.py
│   ├── requirements.txt
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

🌟 Key Features Demonstrated

DocumentDB Capabilities

  • ✅ BSON document storage
  • ✅ MongoDB wire protocol compatibility
  • ✅ Complex aggregation pipelines
  • ✅ Indexing strategies
  • ✅ Full-text search (optional)
  • ✅ Vector search for AI workloads (optional)

FastAPI Best Practices

  • ✅ Async/await patterns
  • ✅ Pydantic validation
  • ✅ Automatic OpenAPI documentation
  • ✅ Dependency injection
  • ✅ Error handling
  • ✅ CORS configuration

Docker Best Practices

  • ✅ Multi-stage builds
  • ✅ Environment variable management
  • ✅ Volume mounting for development
  • ✅ Health checks
  • ✅ Network isolation

📄 License

This project is licensed under the MIT License.

🔗 Resources

Official Documentation

DocumentDB for VS Code Extension

Additional Resources