ada-backend 0.1.0
FastAPI + SQLAlchemy 2.0 async CRUD API with JWT auth, pagination, Alembic migrations, and Docker support
Requires Python: >=3.10

# FastAPI CRUD API

A modern, production-ready CRUD API built with **FastAPI**, **SQLAlchemy 2.0**, **Alembic**, and **PostgreSQL** (easily swappable with SQLite/MySQL).

Features:

- Full CRUD operations
- Async SQLAlchemy 2.0 + Pydantic v2
- Automatic OpenAPI (Swagger) documentation
- JWT authentication (optional, ready to enable)
- Pagination, filtering, and sorting
- Docker & Docker Compose support
- Alembic migrations
- Pre-commit hooks & Ruff linting
- Testing with pytest + httpx

## 🚀 Quick Start

### Prerequisites

- Python 3.11+
- Docker & Docker Compose (optional but recommended)

### 1. Clone the repository

```bash
git clone https://github.com/yosefalemu/fastapi-crud-api.git
cd fastapi-crud-api
```

### 2. Create and activate virtual environment

```bash
python -m venv venv
source venv/bin/activate    # Linux/Mac
# or
venv\Scripts\activate       # Windows
```

### 3. Install dependencies

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

### 4. Copy environment file

```bash
cp .env.example .env
```

Then edit `.env` with your settings (database URL, secret key, etc.)

### 5. Run migrations

```bash
alembic upgrade head
```

### 6. Start the server

```bash
uvicorn app.main:app --reload
```

Server will be available at: http://127.0.0.1:8000  
Interactive docs:

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

## 🐳 Using Docker (Recommended for production-like environment)

```bash
docker compose up --build
```

The API will be available at http://localhost:8000

## 📋 API Endpoints (Example: Item resource)

| Method | Endpoint      | Description            | Auth Required |
| ------ | ------------- | ---------------------- | ------------- |
| POST   | `/items/`     | Create item            | No            |
| GET    | `/items/`     | List items (paginated) | No            |
| GET    | `/items/{id}` | Get single item        | No            |
| PUT    | `/items/{id}` | Update item            | Yes (admin)   |
| DELETE | `/items/{id}` | Delete item            | Yes (admin)   |
| POST   | `/auth/token` | Login & get JWT token  | No            |

> Full interactive documentation available at `/docs`

## 🧪 Running Tests

```bash
pytest
```

Or with coverage:

```bash
pytest --cov=app
```

## 🔧 Environment Variables (`.env`)

```env
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/fastapi_crud
SECRET_KEY=your-super-secret-jwt-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
ENVIRONMENT=development
```

## 🗄️ Database Migrations (Alembic)

```bash
# Create a new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Downgrade
alembic downgrade -1
```

## 🪝 Pre-commit (recommended)

```bash
pre-commit install
```

This project uses:

- Ruff (linter & formatter)
- Black
- mypy
- flake8

## 📁 Project Structure

```
.
├── app/
│   ├── api/          # All routers & endpoints
│   ├── core/         # Config, security, dependencies
│   ├── crud/         # CRUD operations
│   ├── models/       # SQLAlchemy models
│   ├── schemas/      # Pydantic schemas
│   ├── main.py       # FastAPI app instance
│   └── database.py   # DB session & engine
├── migrations/       # Alembic migrations
├── tests/            # pytest tests
├── .env.example
├── requirements.txt
├── docker-compose.yml
└── README.md
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

Your Name – [@yosefalemu](https://twitter.com/yourhandle)

## ⭐ Show your support

Give a ⭐️ if this project helped you!

---

Made with ❤️ using FastAPI