Student CRUD API

A production-ready Flask service that exposes versioned REST endpoints for managing student records. The project was built as part of an SRE bootcamp to demonstrate Twelve-Factor App practices, clean layering, automated migrations, Postman documentation, and a comprehensive unit-test suite.

Table of Contents

1. Learning Outcomes & Feature Highlights
2. Tech Stack
3. Repository Layout
4. Prerequisites
5. Setup & Local Development
6. Configuration
7. Database Migrations
8. Running the API
9. Testing
10. API Surface
11. Postman Collection
12. Logging & Observability
13. Further Improvements

---

Learning Outcomes & Feature Highlights

• Twelve-Factor friendly: runtime configuration via environment variables, strict separation of config vs code, explicit dependency declaration, and stateless workers.
• REST best practices: versioned routes (/api/v1), proper HTTP verbs, structured validation errors, and idempotent update/delete handlers.
• Full CRUD coverage: create, list, retrieve, update, and delete students backed by SQLAlchemy models.
• Health monitoring: /healthcheck at the blueprint level and a root /healthcheck to integrate with container orchestration probes.
• Migration-ready: lightweight script that materializes the schema through SQLAlchemy metadata.
• Automation hooks: Make targets for installing deps, running migrations, launching the server, and executing tests.
• Unit tests: pytest suite with isolated SQLite databases per test to avoid cross-test data bleed.
• Postman documentation: sharable collection covering the golden-path requests expected during the bootcamp demo.

Tech Stack

• Python 3.12
• Flask 3.x + Flask-SQLAlchemy 3.x
• SQLite (default) or any SQLAlchemy-supported RDBMS via DATABASE_URL
• Pytest 8.x
• Make for reproducible local workflows

Repository Layout

app/                Flask application factory, models, and routes
instance/           Local SQLite database (gitignored in real deployments)
migrations/         Simple migration scripts (db.create_all bootstrap)
postman/            Postman collection describing the REST surface
tests/              Pytest suite + fixtures
run.py              Entry point used by `make run`
requirements.txt    Locked dependency set
Makefile            Developer workflow automation
README.md           This document

Prerequisites

• Python ≥ 3.11 (tested with 3.12)
• make
• A shell capable of exporting environment variables

Setup & Local Development

git clone https://github.com/<your-account>/student-api.git
cd student-api

# 1. Create the virtual environment and install deps
make install

# 2. Provide configuration (see next section)
cp .env.example .env   # if you create one, or export the variables manually

Tip: make install implicitly runs python -m venv .venv (via the venv target) and then installs from requirements.txt. All subsequent Make targets use the same virtual environment.

Configuration

The service is configured entirely via environment variables (no hard-coded secrets).

Variable	Required	Default	Description
DATABASE_URL	✅	—	SQLAlchemy DSN (e.g., sqlite:///instance/students.db or postgresql://user:pass@host/db).
LOG_LEVEL	❌	INFO	Python logging level (DEBUG, INFO, WARNING, etc.).
FLASK_ENV	❌	production	Controls Flask debug mode; the Makefile sets this to development for make run.

For local development you can drop a .env file (loaded via python-dotenv):

DATABASE_URL=sqlite:///instance/students.db
LOG_LEVEL=DEBUG

Database Migrations

This project uses SQLAlchemy’s metadata to create the schema. Run the bootstrap migration whenever you change models or want a fresh database:

make migrate

The command executes migrations/create_tables.py, which builds an application context and calls db.create_all(). You can point DATABASE_URL at SQLite, Postgres, or any other supported database before running the migration.

Running the API

make run

This command:

1. Ensures the virtual environment exists.
2. Sets FLASK_ENV=development for nicer errors.
3. Starts the API on http://localhost:5000.

Alternatively, run source .venv/bin/activate && python run.py.

Testing

Unit tests are powered by pytest. Each test function receives the client fixture from tests/conftest.py, which wires up a per-test SQLite file for perfect isolation.

make test
# or
source .venv/bin/activate && PYTHONPATH=. pytest

API Surface

Method	Path	Description	Success Codes
GET	/api/v1/healthcheck	Versioned health probe	200
GET	/healthcheck	Root health probe (no version)	200
POST	/api/v1/students	Create a student	201
GET	/api/v1/students	List all students	200
GET	/api/v1/students/{id}	Fetch a student by id	200, 404
PUT	/api/v1/students/{id}	Update name/email/age	200, 404, 409
DELETE	/api/v1/students/{id}	Delete a student	200, 404

Validation errors respond with 400 and an {"error": "..."} payload. Duplicate emails return 409 Conflict.

Postman Collection

A ready-to-import Postman collection lives under postman/student-api.postman_collection.json. It contains requests for:

• Healthcheck
• Create/List/Get/Update/Delete student flows

Usage:

1. Open Postman → “Import”.
2. Select the JSON file.
3. Optionally override the baseUrl variable (default http://localhost:5000/api/v1).

Logging & Observability

• Logging configuration is centralized in app/__init__.py, honoring the LOG_LEVEL env var.
• routes_v1.py emits structured logs for create/update/delete success paths and warns on missing/duplicate data.
• When running under a process manager (Gunicorn, systemd), configure log aggregation to capture stdout/stderr.

Further Improvements

• Add Alembic for schema diffs instead of db.create_all().
• Introduce pagination for GET /students.
• Extend validation (e.g., email format, age bounds) using Marshmallow or Pydantic.
• Deploy behind Gunicorn with container-ready Dockerfiles and CI pipelines.

---

Brought to you by the SRE Bootcamp — showcasing clean REST design, Twelve-Factor discipline, and actionable observability.