A production-grade REST API for the Democratic Republic of Congo minerals production dataset. Built with FastAPI and PostgreSQL, it exposes 270 records spanning 25 mineral types across 18 provinces from 2010 to 2024.
The dataset was created and curated by Qetsia Nkulu as part of this project. Some records reference data sourced from the Enough Project, a non-profit organization focused on conflict minerals and human rights in Central Africa.
Note: The email addresses and organization names appearing in the audit trail fields (created_by, updated_by) are fake and used for illustrative purpose only. The dataset was intentionally designed to simulate real production in cloud data systems.
The dataset covers mineral production records from the Democratic Republic of Congo:
- 270 records across 25 unique minerals
- 18 provinces including Haut-Katanga, Lualaba, and North Kivu
- 2010–2024 year range
- Fields include confidence scores, data quality flags, audit trails, and soft delete support
- FastAPI — high-performance Python web framework
- PostgreSQL — relational database
- SQLAlchemy — ORM and database toolkit
- Alembic — versioned database migrations
- Pydantic — data validation and serialization
- pytest — automated test suite
drc-minerals-api/
├── app/
│ ├── api/v1/endpoints/ # Route handlers
│ ├── core/ # Config and settings
│ ├── db/ # Database session and base
│ ├── models/ # SQLAlchemy table definitions
│ ├── schemas/ # Pydantic request/response models
│ └── services/ # Business logic and queries
├── alembic/ # Database migrations
├── scripts/ # Seed script
├── tests/ # pytest suite
├── main.py # Application entry point
└── requirements.txt
- Python 3.10+
- PostgreSQL 14+
git clone https://github.com/YOUR_USERNAME/drc-minerals-api.git
cd drc-minerals-apipython3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txtcp .env.example .envEdit .env with your PostgreSQL credentials:
DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/drc_minerals
APP_ENV=development
DEBUG=true
psql -U postgres -c "CREATE DATABASE drc_minerals;"alembic upgrade headpython3 scripts/seed.pyuvicorn main:app --reloadVisit http://127.0.0.1:8000/docs for the interactive Swagger UI.
| Method | Endpoint | Description |
|---|---|---|
GET |
/ |
Health check and project info |
GET |
/health |
Server status |
GET |
/api/v1/minerals/ |
List all minerals with filters and pagination |
GET |
/api/v1/minerals/summary |
Aggregate stats by category, region, and year |
GET |
/api/v1/minerals/{record_id} |
Get a single mineral record |
POST |
/api/v1/minerals/ |
Create a new mineral record |
PATCH |
/api/v1/minerals/{record_id} |
Partially update a record |
DELETE |
/api/v1/minerals/{record_id} |
Soft delete a record |
The GET /api/v1/minerals/ endpoint supports the following query parameters:
| Parameter | Type | Description |
|---|---|---|
region |
string | Filter by province (case-insensitive partial match) |
category |
string | Filter by mineral category |
year |
integer | Filter by year recorded |
mining_status |
string | Filter by Active, Inactive, or Artisanal |
is_verified |
boolean | Filter by verification status |
skip |
integer | Pagination offset (default: 0) |
limit |
integer | Page size (default: 100, max: 500) |
Example:
GET /api/v1/minerals/?region=Haut-Katanga&category=Base Metal&is_verified=true
python3 -m pytest tests/ -v- Soft deletes — records are never hard-deleted;
is_activeanddeleted_atpreserve history - Alembic migrations — every schema change is versioned and reproducible
- Service layer — business logic is fully separated from HTTP route handlers
- Pydantic validation — all input is validated before touching the database
- Dependency injection — database sessions are managed automatically per request
- Environment-based config — no hardcoded credentials anywhere in the codebase