Monastery-Web-API

Overview

Monastery CRUD API is a production‑style backend service implemented with Flask that exposes a RESTful interface for managing monastery records. The application is integrated with a MySQL server using a connection pool for efficient, concurrent database access. The codebase is organized to separate concerns between routing, domain models, database access, and error handling. Interactive API documentation is provided via Swagger UI and the project includes automated unit tests to ensure correctness and prevent regressions.

---

Key Features

• Full CRUD surface for monastery resources with endpoints for create, read, update, partial update, and delete.
• MySQL server integration using a connection pool to maintain performant and stable database connections.
• Swagger UI automatically generated from route definitions to expose endpoint schemas, parameters, and responses.
• Model‑level validation that enforces data integrity before persistence; validation failures raise domain exceptions.
• Custom exception hierarchy mapped to HTTP status codes to produce consistent, structured JSON error responses.
• Centralized logging that records errors and operational events to a dedicated log file for debugging and auditability.
• Unit tests covering model logic and API endpoints using Python’s unittest framework.
• Configuration via environment variables with a .env.example template included to document required settings without exposing secrets.
• Optional Docker Compose configuration for reproducible local integration environments (MySQL + Flask).

---

Architecture and Components

• Flask Application Layer
  The application layer handles routing, request parsing, response formatting, and Swagger registration. Routes are organized to keep controllers thin and focused on HTTP concerns.

• Model Layer
  Domain models encapsulate validation and transformation logic for monastery entities. All input validation and domain rules are enforced here; models raise domain exceptions on invalid data.

• Database Layer
  A dedicated database module manages a MySQL connection pool and exposes reusable CRUD operations. SQL access is isolated from business logic to simplify testing and maintenance.

• Exception Layer
  Custom exception types and a global error handler convert internal errors into consistent JSON responses and ensure that error details are logged to errors.log.

• Testing Layer
  Unit tests exercise model validation, error conditions, and each API route’s expected behavior. Tests are structured to be runnable in isolation and to provide clear assertions for regressions.

---

Configuration

Environment variables are used for all environment‑specific settings. Sensitive values are excluded from version control. The repository includes a .env.example file that documents required variables and expected names.

Example .env variables (documented in .env.example):

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=mon_user
DB_PASS=strong_password
DB_NAME=monasteries_db
FLASK_ENV=development
FLASK_DEBUG=1
SECRET_KEY=replace_with_secure_key

Testing and Deployment

Testing

Unit tests
The project includes a comprehensive unit test suite implemented with Python’s unittest framework. Tests are located in the tests/ directory and cover:

• Model validation and domain rules for monastery entities.
• API behavior for each endpoint, including success cases and expected error responses.
• Exception handling to ensure consistent JSON error payloads and proper logging.

Run tests locally

# from project root
python -m unittest discover tests

API Endpoints Reference

Base path: /api/monasteries
Content-Type: application/json

Method	Endpoint	Description	Request Body	Success Response
GET	/api/monasteries	List all monasteries	none	200 OK — JSON array of monastery objects
GET	/api/monasteries/{id}	Get monastery by ID	none	200 OK — single monastery object
GET	/api/monasteries/location/{location}	Find monasteries by location	none	200 OK — array filtered by location
GET	/api/monasteries/year/{year}	Find monasteries by year of construction	none	200 OK — array filtered by year
GET	/api/monasteries/name/{name}	Find monasteries by name	none	200 OK — array filtered by name
POST	/api/monasteries	Create new monastery	JSON with name, location, optional year_of_construction, description	201 Created — created monastery object
PUT	/api/monasteries/{id}	Replace monastery record (full update)	Full JSON resource (all required fields)	200 OK — updated monastery object
PATCH	/api/monasteries/{id}	Partial update of monastery record	Partial JSON (only fields to change)	200 OK — updated monastery object
DELETE	/api/monasteries/{id}	Delete monastery record	none	204 No Content — resource deleted

---

Example Request

List all monasteries

curl -sS http://localhost:5000/api/monasteries

Example Monastery Object (JSON)

{
  "id": 1,
  "name": "Studenica",
  "location": "Central Serbia",
  "year_of_construction": 1190,
}

Screenshots

License

This project is licensed under the MIT License.