Generic REST API Service

This is a FastAPI application that provides a simple generic REST API service with CRUD operations for an "Item" resource.

Features

• FastAPI-based RESTful API
• SQLite database with SQLAlchemy ORM
• Alembic for database migrations
• Pydantic for data validation
• Comprehensive CRUD operations
• Health check endpoint
• Automatic OpenAPI documentation

Project Structure

├── alembic/                  # Database migration files
│   ├── versions/             # Migration version scripts
│   ├── env.py                # Alembic environment configuration
│   └── script.py.mako        # Migration script template
├── app/                      # Application package
│   ├── api/                  # API routes
│   │   ├── endpoints/        # API endpoint modules
│   │   ├── api.py            # API router setup
│   │   └── deps.py           # Dependency injection functions
│   ├── core/                 # Core application modules
│   │   └── config.py         # Application configuration
│   ├── crud/                 # CRUD operation modules
│   │   ├── base.py           # Base CRUD operations
│   │   └── crud_item.py      # Item-specific CRUD operations
│   ├── db/                   # Database modules
│   │   ├── base.py           # Import all models
│   │   ├── base_class.py     # Base model class
│   │   ├── init_db.py        # Database initialization
│   │   └── session.py        # DB session setup
│   ├── models/               # SQLAlchemy models
│   │   └── item.py           # Item model
│   └── schemas/              # Pydantic schemas
│       └── item.py           # Item schema
├── alembic.ini               # Alembic configuration
├── main.py                   # Application entry point
├── requirements.txt          # Project dependencies
├── start.sh                  # Production startup script
└── supervisor.conf           # Supervisor configuration

Setup and Installation

1. Clone the repository:

git clone <repository-url>
cd generic-rest-api-service

2. Create and activate a virtual environment (optional, but recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\\Scripts\\activate

3. Install dependencies:

pip install -r requirements.txt

4. Run database migrations:

# Make sure you are in the project root directory
alembic upgrade head

# If you encounter any module import errors, you can also try:
PYTHONPATH=$PWD alembic upgrade head

5. Start the application:

Development mode:

uvicorn main:app --reload

The application will be available at http://127.0.0.1:8000.

Production mode with Supervisor:

The application comes with a Supervisor configuration file for production deployment. Follow these steps carefully:

# Make the start script executable
chmod +x start.sh

# Test the start script manually to verify it works
./start.sh
# Press Ctrl+C to stop after verifying

# Create necessary directories for logs (if not using default location)
sudo mkdir -p /var/log/supervisor
sudo chmod 777 /var/log/supervisor

# Copy the supervisor configuration to the supervisor config directory
# If you're not running as root, you'll need sudo:
sudo cp supervisor.conf /etc/supervisor/conf.d/fastapi-app.conf

# Ensure supervisor is installed and running
# On Debian/Ubuntu:
sudo apt-get update && sudo apt-get install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor

# Reload supervisor configuration (always do both commands)
sudo supervisorctl reread
sudo supervisorctl update

# Check the status of the application
sudo supervisorctl status app-8001

# If it shows BACKOFF or FATAL status, check the logs:
sudo tail -f /var/log/supervisor/app-8001.log

# To restart the application after making changes:
sudo supervisorctl restart app-8001

# To stop the application:
sudo supervisorctl stop app-8001

Troubleshooting Supervisor Issues

If you encounter issues with Supervisor:

1. Check permissions: Ensure the user specified in supervisor.conf has access to all required directories

2. Check paths: Verify all paths in supervisor.conf and start.sh are correct for your environment

3. View detailed logs: Check supervisor logs for specific error messages

   sudo cat /var/log/supervisor/supervisord.log
   

4. Debug the start script: Run the start script manually to see if it works

   ./start.sh
   

5. Check environment variables: Ensure all required environment variables are set in supervisor.conf

The application will be available at http://127.0.0.1:8001 when running with Supervisor.

API Documentation

Once the application is running, you can access the automatically generated API documentation:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

API Endpoints

Health Check

• GET /api/v1/health: Check if the service is healthy

Items

• GET /api/v1/items: List all items
  • Query parameters:
    • skip: Number of items to skip (default: 0)
    • limit: Maximum number of items to return (default: 100)
    • active_only: If true, return only active items (default: false)
• POST /api/v1/items: Create a new item
• GET /api/v1/items/{id}: Get a specific item by ID
• PUT /api/v1/items/{id}: Update a specific item
• DELETE /api/v1/items/{id}: Delete a specific item (returns 204 No Content)

Development

Running Tests

# Add test command here

Linting with Ruff

ruff check .
ruff format .