genericrestapiservice-efavmm/README.md

# 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:

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

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

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

3. Install dependencies:

```bash
pip install -r requirements.txt
```

4. Run database migrations:

```bash
# 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:**

```bash
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:

```bash
# 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
   ```bash
   sudo cat /var/log/supervisor/supervisord.log
   ```

4. **Debug the start script**: Run the start script manually to see if it works
   ```bash
   ./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

```bash
# Add test command here
```

### Linting with Ruff

```bash
ruff check .
ruff format .
```