This is a FastAPI-based REST API application for managing customers and their addresses using Azure Cosmos DB. The project demonstrates spec-driven development using Visual Studio Code and various LLMs.

• Customer Management: Complete CRUD operations for customer records
• Address Management: Complete CRUD operations for customer addresses
• Azure Cosmos DB Integration: Leveraging Azure Cosmos DB for data persistence
• Data Validation: Comprehensive input validation using Pydantic models
• Comprehensive Testing: Unit tests with pytest
• API Documentation: Auto-generated OpenAPI/Swagger documentation

The application follows a clean architecture pattern with:

• FastAPI: Modern, fast web framework for building APIs
• Pydantic: Data validation and serialization using Python type annotations
• Azure Cosmos DB: NoSQL database for scalable data storage
• Pytest: Testing framework with comprehensive test coverage

• POST /api/customers - Create a new customer
• GET /api/customers - List customers with pagination
• GET /api/customers/{customerId} - Get a specific customer
• PUT /api/customers/{customerId} - Update a customer
• DELETE /api/customers/{customerId} - Delete a customer

• POST /api/customers/addresses - Create a new customer address
• GET /api/customers/{customerId}/addresses - List addresses for a customer
• GET /api/customers/{customerId}/addresses/{addressId} - Get a specific address
• PUT /api/customers/{customerId}/addresses/{addressId} - Update an address
• DELETE /api/customers/{customerId}/addresses/{addressId} - Delete an address

• Python 3.12 or higher
• Azure Cosmos DB account and connection string
• uv package manager

git clone <repository-url> cd spec-driven-dev-backend-apis

Using uv (recommended):

uv sync

Or using pip:

pip install -r requirements.txt

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env file with your Azure Cosmos DB configuration:

COSMOS_CONNECTION_STRING=AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-primary-key; COSMOS_DATABASE_NAME=contoso_customer_db

The application will automatically create the database and containers on first run. Ensure your Cosmos DB account has sufficient permissions.

# Using uv uv run python main.py # Or using python directly python main.py

The API will be available at:

• API Base URL: http://localhost:8000
• Interactive Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

# Using uvicorn directly uvicorn main:app --host 0.0.0.0 --port 8000 # With multiple workers uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Run the comprehensive test suite:

# Run all tests uv run pytest # Run with coverage uv run pytest --cov=contoso_api_backend # Example to Run specific test files uv run pytest tests/test_customers.py uv run pytest tests/test_addresses.py uv run pytest tests/test_models.py

{ "id": "string (UUID)", "firstName": "string", "lastName": "string", "accountCategory": "Free | Standard | Premium" }

{ "id": "string (UUID)", "customerId": "string (UUID)", "address": "string", "address2": "string (optional)", "city": "string", "state": "string (2-letter code)", "zipCode": "string (12345 or 12345-6789)", "addressType": "shipping | billing" }

You can test the API using the humao.rest-client VSCode extension or any HTTP client like curl or Postman.

POST http://localhost:8000/api/customers Content-Type: application/json { "firstName": "John", "lastName": "Doe", "accountCategory": "Standard" }

POST http://localhost:8000/api/customers/addresses Content-Type: application/json { "customerId": "123e4567-e89b-12d3-a456-426614174000", "address": "123 Main St", "address2": "Apt 4B", "city": "Seattle", "state": "WA", "zipCode": "98101", "addressType": "shipping" }

spec-driven-dev-backend-apis/ ├── contoso_api_backend/ # Main application package │ ├── __init__.py │ ├── models.py # Pydantic data models │ ├── database.py # Cosmos DB connection management │ ├── customers.py # Customer endpoint handlers │ └── addresses.py # Address endpoint handlers ├── tests/ # Test suite │ ├── __init__.py │ ├── conftest.py # Test fixtures │ ├── test_customers.py # Customer endpoint tests │ ├── test_addresses.py # Address endpoint tests │ └── test_models.py # Model validation tests ├── main.py # FastAPI application entry point ├── pyproject.toml # Project dependencies and metadata ├── .env.example # Environment configuration template └── README.md # This file 

The API includes comprehensive error handling with appropriate HTTP status codes:

• 200 OK - Successful GET/PUT operations
• 201 Created - Successful POST operations
• 204 No Content - Successful DELETE operations
• 404 Not Found - Resource not found
• 422 Unprocessable Entity - Validation errors
• 400 Bad Request - General client errors
• 500 Internal Server Error - Server errors

1. Follow the existing code structure and patterns
2. Add comprehensive tests for new features
3. Update documentation as needed
4. Ensure all tests pass before submitting changes

This project is licensed under the MIT License - see the LICENSE file for details.