Forem: Ameh Mathias Ejeh

School Library System API

Ameh Mathias Ejeh — Sun, 29 Mar 2026 16:45:39 +0000

A RESTful API for managing a school library — authors, books, students, library attendants, and book borrowing/returns. Built with Node.js (ESM), Express.js, and MongoDB/Mongoose.

Features
Tech Stack
Project Structure
Setup & Installation
Environment Variables
API Documentation
- Authentication
- Authors
- Books
- Students
- Attendants
Postman Collection
Business Rules

Features

Full CRUD for Authors, Books, Students, and Library Attendants
Book borrowing and returning with full relationship tracking
Auto-population of authors, student, and attendant when a book is OUT
Overdue detection (isOverdue flag on responses)
Pagination on all list endpoints
Search by title or author name
Duplicate ISBN prevention (unique index + 409 error)
Request validation with express-validator
JWT authentication (attendants log in and receive a token)
Global error handler with meaningful messages
ESM imports throughout (no CommonJS)

Tech Stack

Layer	Technology
Runtime	Node.js (ESM)
Framework	Express.js
Database	MongoDB via Mongoose
Auth	JSON Web Tokens (jsonwebtoken)
Passwords	bcryptjs
Validation	express-validator
Config	dotenv

Project Structure

library-system/
├── config/
│   └── db.js                  # MongoDB connection
├── controllers/
│   ├── authorController.js
│   ├── bookController.js
│   ├── studentController.js
│   └── attendantController.js
├── middleware/
│   ├── auth.js                # JWT protect middleware
│   ├── errorHandler.js        # Global error handler
│   └── validators.js          # express-validator rules
├── models/
│   ├── Author.js
│   ├── Book.js
│   ├── Student.js
│   └── LibraryAttendant.js
├── routes/
│   ├── authorRoutes.js
│   ├── bookRoutes.js
│   ├── studentRoutes.js
│   └── attendantRoutes.js
├── .env.example
├── package.json
├── app.js
└── README.md

Setup & Installation

Prerequisites

Node.js
MongoDB running locally or a MongoDB Atlas URI

Steps

# 1. Clone the repository
git clone <repo-url>
cd school-library-system

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your values

# 4. Start the server
npm start          # production
npm run dev        # development (auto-restarts on file changes)

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

Health check: GET http://localhost:5000/health

Environment Variables

PORT=5000
MONGO_URI=mongodb://localhost:27017/library-system
JWT_SECRET=your_super_secret_jwt_key_change_in_production
JWT_EXPIRES_IN=7d

Variable	Description	Default
`PORT`	Port the server listens on	`5000`
`MONGO_URI`	MongoDB connection string	`mongodb://localhost:27017/library-system`
`JWT_SECRET`	Secret for signing JWT tokens	(required)
`JWT_EXPIRES_IN`	Token expiry duration	`7d`

API Documentation

Base URL: http://localhost:5000/api/v1

Response Format

All responses follow a consistent envelope:

{
  "success": true,
  "data": { ... },
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}

Errors:

{
  "success": false,
  "message": "Human-readable error message",
  "errors": [{ "field": "email", "message": "Invalid email" }]
}

Pagination & Filtering (all GET list endpoints)

Query Param	Type	Description
`page`	Number	Page number (default: 1)
`limit`	Number	Results per page (default: 10)
`search`	String	Search term (varies by resource)

Authentication

JWT is required for all write operations and sensitive reads. Login as an attendant to get a token.

Protected routes require the header:

Authorization: Bearer <token>

POST `/attendants/login`

Request Body:

{
  "email": "ameh@library.edu",
  "password": "secret123"
}

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "data": {
    "_id": "664abc...",
    "name": "Ameh Mathias",
    "staffId": "STF001",
    "email": "ameh@library.edu"
  }
}

Authors

Method	Endpoint	Auth	Description
GET	`/authors`	No	List all authors
GET	`/authors/:id`	No	Get single author
POST	`/authors`	Yes	Create author
PUT	`/authors/:id`	Yes	Update author
DELETE	`/authors/:id`	Yes	Delete author

GET `/authors`

Query params: page, limit, search (matches name).

Response:

{
  "success": true,
  "data": [
    {
      "_id": "664abc123...",
      "name": "Chinua Achebe",
      "bio": "Nigerian novelist and poet.",
      "createdAt": "2024-06-01T10:00:00.000Z"
    }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 10, "pages": 1 }
}

POST `/authors` 🔒

{
  "name": "Chinua Achebe",
  "bio": "Nigerian novelist and poet."
}

PUT `/authors/:id` 🔒

{
  "bio": "Updated biography text."
}

Books

Method	Endpoint	Auth	Description
GET	`/books`	No	List books (paginated)
GET	`/books/:id`	No	Get single book
POST	`/books`	Yes	Create book
PUT	`/books/:id`	Yes	Update book
DELETE	`/books/:id`	Yes	Delete book (must be IN)
POST	`/books/:id/borrow`	Yes	Borrow a book
POST	`/books/:id/return`	Yes	Return a book

GET `/books`

Query params: page, limit, search (title), author (author name), status (IN or OUT).

Response when status = OUT:

{
  "success": true,
  "data": [{
    "_id": "664abc...",
    "title": "Things Fall Apart",
    "isbn": "978-0-385-47454-2",
    "status": "OUT",
    "isOverdue": false,
    "returnDate": "2024-07-01T00:00:00.000Z",
    "authors": [{ "_id": "...", "name": "Chinua Achebe", "bio": "..." }],
    "borrowedBy": { "_id": "...", "name": "Emeka Obi", "studentId": "STU001" },
    "issuedBy": { "_id": "...", "name": "Jane Doe", "staffId": "STF001" }
  }]
}

POST `/books` 🔒

{
  "title": "Things Fall Apart",
  "isbn": "978-0-385-47454-2",
  "authors": ["664abc123..."]
}

POST `/books/:id/borrow` 🔒

Book must have status: "IN".

{
  "studentId": "664def456...",
  "attendantId": "664ghi789...",
  "returnDate": "2024-07-15T00:00:00.000Z"
}

Response:

{
  "success": true,
  "message": "Book borrowed successfully.",
  "data": {
    "_id": "...",
    "title": "Things Fall Apart",
    "status": "OUT",
    "returnDate": "2024-07-15T00:00:00.000Z",
    "borrowedBy": { "name": "Emeka Obi", "studentId": "STU001" },
    "issuedBy": { "name": "Jane Doe", "staffId": "STF001" }
  }
}

POST `/books/:id/return` 🔒

Book must have status: "OUT". No request body needed.

Response:

{
  "success": true,
  "message": "Book returned successfully.",
  "data": {
    "_id": "...",
    "title": "Things Fall Apart",
    "status": "IN",
    "borrowedBy": null,
    "issuedBy": null,
    "returnDate": null
  }
}

Students

Method	Endpoint	Auth	Description
GET	`/students`	Yes	List all students
GET	`/students/:id`	Yes	Get single student (includes borrowed books)
POST	`/students`	Yes	Create student
PUT	`/students/:id`	Yes	Update student
DELETE	`/students/:id`	Yes	Delete student (cannot have active loans)

POST `/students` 🔒

{
  "name": "Emeka Obi",
  "email": "emeka@school.edu",
  "studentId": "STU001"
}

GET `/students/:id` 🔒

Includes currently borrowed books with overdue status:

{
  "success": true,
  "data": {
    "_id": "...",
    "name": "Emeka Obi",
    "email": "emeka@school.edu",
    "studentId": "STU001",
    "borrowedBooks": [
      {
        "_id": "...",
        "title": "Things Fall Apart",
        "isbn": "978-0-385-47454-2",
        "returnDate": "2024-06-30T00:00:00.000Z",
        "isOverdue": true
      }
    ]
  }
}

Attendants

Method	Endpoint	Auth	Description
POST	`/attendants/login`	No	Login and get token
GET	`/attendants`	Yes	List all attendants
GET	`/attendants/:id`	Yes	Get single attendant
POST	`/attendants`	Yes	Create attendant
PUT	`/attendants/:id`	Yes	Update attendant
DELETE	`/attendants/:id`	Yes	Delete attendant

POST `/attendants` 🔒

{
  "name": "James Godwin",
  "staffId": "STF001",
  "email": "jame@library.edu",
  "password": "secret123"
}

Business Rules

Rule	Detail
Borrow	Book `status` must be `"IN"`. Sets `status → "OUT"`, `borrowedBy`, `issuedBy`, `returnDate`.
Return	Book `status` must be `"OUT"`. Clears `status → "IN"`, nullifies `borrowedBy`, `issuedBy`, `returnDate`.
Delete Book	Blocked if book is currently `"OUT"` (borrowed).
Delete Student	Blocked if student has active borrowed books.
Duplicate ISBN	Returns `409 Conflict` if a book with the same ISBN already exists.
Overdue	Any book where `status = "OUT"` and `returnDate < now` will have `isOverdue: true` in the response.
Populate on OUT	When a book is `"OUT"`, `authors`, `borrowedBy`, and `issuedBy` are always populated in responses.
Auth	All write operations and student/attendant reads require a valid JWT (`Authorization: Bearer <token>`).

Error Reference

Status	Meaning
400	Bad request / business rule violated
401	Missing or invalid JWT
404	Resource not found
409	Duplicate key (e.g., ISBN, email)
422	Validation error
500	Internal server error

GitHub Repo: Link

Onebody API Documentation

Ameh Mathias Ejeh — Thu, 27 Nov 2025 12:15:51 +0000

Base URL: `http://localhost:5000`

Register

POST /api/auth/register

Login

POST /api/auth/login

Create Artiste (Protected)

POST /api/artistes

Response

{
    "success": true,
    "message": "Artiste created successfully",
    "data": {
        "artiste": {
            "id": 4,
            "name": "Samuel Adedayo",
            "desc": "A marvelous gospel singer",
            "image": "uploads\\artistes\\image-1764242219273-893646722.png",
            "updatedAt": "2025-11-27T11:17:00.716Z",
            "createdAt": "2025-11-27T11:17:00.716Z"
        }
    }
}

Get all Artistes

GET /api/artistes

Response

{
    "success": true,
    "count": 4,
    "data": {
        "artistes": [
            {
                "id": 4,
                "name": "Samuel Adedayo",
                "image": "uploads\\artistes\\image-1764242219273-893646722.png",
                "desc": "A marvelous gospel singer",
                "createdAt": "2025-11-27T11:17:00.716Z",
                "updatedAt": "2025-11-27T11:17:00.716Z"
            },
            {
                "id": 3,
                "name": "Tito Pelumi",
                "image": "uploads\\artistes\\image-1764152676621-764537291.png",
                "desc": "A marvelous gospel singer",
                "createdAt": "2025-11-26T10:24:37.237Z",
                "updatedAt": "2025-11-26T10:24:37.237Z"
            },
            {
                "id": 2,
                "name": "Emmanuel Ajose",
                "image": "uploads\\artistes\\image-1764110414208-444407115.png",
                "desc": "A renowned gospel artiste ",
                "createdAt": "2025-11-25T22:40:14.275Z",
                "updatedAt": "2025-11-25T22:44:08.193Z"
            },
            {
                "id": 1,
                "name": "John Kenny",
                "image": "uploads\\artistes\\image-1764110357952-755066802.png",
                "desc": "A marvelous gospel singer",
                "createdAt": "2025-11-25T22:39:18.155Z",
                "updatedAt": "2025-11-25T22:39:18.155Z"
            }
        ]
    }
}

Get Artiste by id

GET /api/artistes/:id

Response

{
    "success": true,
    "data": {
        "artiste": {
            "id": 2,
            "name": "Emmanuel Ajose",
            "image": "uploads\\artistes\\image-1764110414208-444407115.png",
            "desc": "A renowned gospel artiste ",
            "createdAt": "2025-11-25T22:40:14.275Z",
            "updatedAt": "2025-11-25T22:44:08.193Z",
            "albums": [
                {
                    "id": 2,
                    "name": "Here I Am",
                    "artisteId": 2,
                    "releaseYear": 2022,
                    "image": "uploads\\albums\\image-1764111099366-720471625.jpg",
                    "createdAt": "2025-11-25T22:51:39.424Z",
                    "updatedAt": "2025-11-25T22:51:39.424Z"
                }
            ],
            "songs": [
                {
                    "id": 2,
                    "name": "Orin Davadi",
                    "artisteId": 2,
                    "albumId": 1,
                    "lyrics": "Morning light is here\nDrowning out all my fears of the night\nOh delight in me\nLiving word show forth yourself \nAnd eternity is singing\nLike the waves breaking the shores of my heart\nRolling on and on\nNever stopping I’m in awe\n\nOh my heart is pleading Savior come\nSavior won’t you come and help me\nI am tired your mercy all that I need\nYes my heart is singing Savior help \nSavior won’t you help\nIn this life your strength is all that I need\nYour strength is all I need\nSavior come\nOh oh oh\n\nAs this drizzle falls softening testing the state of my heart\nOh your word is rain pouring down farmers are glad\nYet eternity is screaming buckets outs \nsoak it all up while it lasts\nLet my heart be sure even as the seasons return \n\nOh my heart is pleading Savior come\nSavior won’t you come oh\nI am tired your mercy all that I need\nYes my heart is singing Savior help \nSavior won’t you help\nIn this life your strength is all that I need\nYeah\n\nSavior wont you come\nYou strength is all that I need\nOh oh oh\nSavior won’t you come\nHelp me now help me now\nOh oh oh \n\n\nHere’s my offering before I give I know you loved\nmercy more\nLet your fire fall I will give it all all the same hmm\nStill eternity is dancing tambourines and cymbals of\ntime never stop oh\nFor my faith is strong \nI’ll be standing when you return\n \nOh my heart is pleading Savior come\nSavior won’t you come oh\nI am tired your mercy all that I need\nOh my heart is singing help \nSavior help me\nIn this life your strength is all that I need\nAll that I need yeah\nOh oh oh\nI need your help\nI need your help savior\nYou are all that I need\nOh oh\n\nMorning light is here\nDrowning out all my fears of the night\nOh delight in me\nLiving word show forth yourself \n",
                    "image": null,
                    "createdAt": "2025-11-25T23:05:06.873Z",
                    "updatedAt": "2025-11-25T23:05:06.873Z"
                }
            ]
        }
    }
}

Create Album (Protected)

POST /api/albums

Response

{
    "success": true,
    "message": "Album created successfully",
    "data": {
        "album": {
            "id": 3,
            "name": "Mercy",
            "artisteId": 4,
            "releaseYear": 2025,
            "image": "uploads\\albums\\image-1764243719856-4963630.jpg",
            "updatedAt": "2025-11-27T11:42:00.414Z",
            "createdAt": "2025-11-27T11:42:00.414Z"
        }
    }
}

Get all Album

GET /api/albums

Response

{
    "success": true,
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 3,
    "data": {
        "albums": [
            {
                "id": 3,
                "name": "Mercy",
                "artisteId": 4,
                "releaseYear": 2025,
                "image": "uploads\\albums\\image-1764243719856-4963630.jpg",
                "createdAt": "2025-11-27T11:42:00.414Z",
                "updatedAt": "2025-11-27T11:42:00.414Z",
                "artiste": {
                    "id": 4,
                    "name": "Samuel Adedayo",
                    "image": "uploads\\artistes\\image-1764242219273-893646722.png"
                }
            },
            {
                "id": 1,
                "name": "Glorious God",
                "artisteId": 1,
                "releaseYear": 2024,
                "image": "uploads\\albums\\image-1764111430083-847458251.jpg",
                "createdAt": "2025-11-25T22:50:00.036Z",
                "updatedAt": "2025-11-25T22:57:10.117Z",
                "artiste": {
                    "id": 1,
                    "name": "John Kenny",
                    "image": "uploads\\artistes\\image-1764110357952-755066802.png"
                }
            },
            {
                "id": 2,
                "name": "Here I Am",
                "artisteId": 2,
                "releaseYear": 2022,
                "image": "uploads\\albums\\image-1764111099366-720471625.jpg",
                "createdAt": "2025-11-25T22:51:39.424Z",
                "updatedAt": "2025-11-25T22:51:39.424Z",
                "artiste": {
                    "id": 2,
                    "name": "Emmanuel Ajose",
                    "image": "uploads\\artistes\\image-1764110414208-444407115.png"
                }
            }
        ]
    }
}

Get Album by id

GET /api/albums/:id

Response

{
    "success": true,
    "data": {
        "album": {
            "id": 2,
            "name": "Here I Am",
            "artisteId": 2,
            "releaseYear": 2022,
            "image": "uploads\\albums\\image-1764111099366-720471625.jpg",
            "createdAt": "2025-11-25T22:51:39.424Z",
            "updatedAt": "2025-11-25T22:51:39.424Z",
            "artiste": {
                "id": 2,
                "name": "Emmanuel Ajose",
                "image": "uploads\\artistes\\image-1764110414208-444407115.png",
                "desc": "A renowned gospel artiste "
            },
            "songs": [
                {
                    "id": 1,
                    "name": "Morning Light"
                },
                {
                    "id": 8,
                    "name": "Calling on my Saviour"
                }
            ]
        }
    }
}

Create Song (Protected)

POST /api/songs

Response

{
    "success": true,
    "message": "Song created successfully",
    "data": {
        "song": {
            "id": 9,
            "name": "In HIs Presence",
            "artisteId": 1,
            "albumId": 3,
            "lyrics": "Morning light is here\nDrowning out all my fears of the night\nOh delight in me\nLiving word show forth yourself \nAnd eternity is singing\nLike the waves breaking the shores of my heart\nRolling on and on\nNever stopping I’m in awe\n\nOh my heart is pleading Savior come\nSavior won’t you come and help me\nI am tired your mercy all that I need\nYes my heart is singing Savior help \nSavior won’t you help\nIn this life your strength is all that I need\nYour strength is all I need\nSavior come\nOh oh oh\n\nAs this drizzle falls softening testing the state of my heart\nOh your word is rain pouring down farmers are glad\nYet eternity is screaming buckets outs \nsoak it all up while it lasts\nLet my heart be sure even as the seasons return \n\nOh my heart is pleading Savior come\nSavior won’t you come oh\nI am tired your mercy all that I need\nYes my heart is singing Savior help \nSavior won’t you help\nIn this life your strength is all that I need\nYeah\n\nSavior wont you come\nYou strength is all that I need\nOh oh oh\nSavior won’t you come\nHelp me now help me now\nOh oh oh \n\n\nHere’s my offering before I give I know you loved\nmercy more\nLet your fire fall I will give it all all the same hmm\nStill eternity is dancing tambourines and cymbals of\ntime never stop oh\nFor my faith is strong \nI’ll be standing when you return\n \nOh my heart is pleading Savior come\nSavior won’t you come oh\nI am tired your mercy all that I need\nOh my heart is singing help \nSavior help me\nIn this life your strength is all that I need\nAll that I need yeah\nOh oh oh\nI need your help\nI need your help savior\nYou are all that I need\nOh oh\n\nMorning light is here\nDrowning out all my fears of the night\nOh delight in me\nLiving word show forth yourself \n",
            "image": "uploads\\songs\\image-1764244937159-222340483.jpg",
            "createdAt": "2025-11-27T12:02:17.532Z",
            "updatedAt": "2025-11-27T12:02:17.532Z",
            "mainArtiste": {
                "id": 1,
                "name": "John Kenny",
                "image": "uploads\\artistes\\image-1764110357952-755066802.png"
            },
            "album": {
                "id": 3,
                "name": "Mercy",
                "image": "uploads\\albums\\image-1764243719856-4963630.jpg"
            },
            "featuredArtistes": [
                {
                    "id": 2,
                    "name": "Emmanuel Ajose",
                    "image": "uploads\\artistes\\image-1764110414208-444407115.png"
                },
                {
                    "id": 3,
                    "name": "Tito Pelumi",
                    "image": "uploads\\artistes\\image-1764152676621-764537291.png"
                }
            ]
        }
    }
}

Get all Songs

GET /api/songs

Response

{
    "success": true,
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 4,
    "data": {
        "songs": [
            {
                "id": 9,
                "name": "In HIs Presence",
                "image": "uploads\\songs\\image-1764244937159-222340483.jpg",
                "createdAt": "2025-11-27T12:02:17.532Z"
            },
            {
                "id": 8,
                "name": "Calling on my Saviour",
                "image": null,
                "createdAt": "2025-11-27T10:48:44.576Z"
            },
            {
                "id": 2,
                "name": "Orin Davadi",
                "image": null,
                "createdAt": "2025-11-25T23:05:06.873Z"
            },
            {
                "id": 1,
                "name": "Morning Light",
                "image": null,
                "createdAt": "2025-11-25T23:03:20.744Z"
            }
        ]
    }
}

Get Song by id

GET /api/songs/:id

Response

{
    "success": true,
    "data": {
        "song": {
            "id": 8,
            "name": "Calling on my Saviour",
            "artisteId": 3,
            "albumId": 2,
            "lyrics": "Morning light is here\nDrowning out all my fears of the night\nOh delight in me\nLiving word show forth yourself \nAnd eternity is singing\nLike the waves breaking the shores of my heart\nRolling on and on\nNever stopping I’m in awe\n\nOh my heart is pleading Savior come\nSavior won’t you come and help me\nI am tired your mercy all that I need\nYes my heart is singing Savior help \nSavior won’t you help\nIn this life your strength is all that I need\nYour strength is all I need\nSavior come\nOh oh oh\n\nAs this drizzle falls softening testing the state of my heart\nOh your word is rain pouring down farmers are glad\nYet eternity is screaming buckets outs \nsoak it all up while it lasts\nLet my heart be sure even as the seasons return \n\nOh my heart is pleading Savior come\nSavior won’t you come oh\nI am tired your mercy all that I need\nYes my heart is singing Savior help \nSavior won’t you help\nIn this life your strength is all that I need\nYeah\n\nSavior wont you come\nYou strength is all that I need\nOh oh oh\nSavior won’t you come\nHelp me now help me now\nOh oh oh \n\n\nHere’s my offering before I give I know you loved\nmercy more\nLet your fire fall I will give it all all the same hmm\nStill eternity is dancing tambourines and cymbals of\ntime never stop oh\nFor my faith is strong \nI’ll be standing when you return\n \nOh my heart is pleading Savior come\nSavior won’t you come oh\nI am tired your mercy all that I need\nOh my heart is singing help \nSavior help me\nIn this life your strength is all that I need\nAll that I need yeah\nOh oh oh\nI need your help\nI need your help savior\nYou are all that I need\nOh oh\n\nMorning light is here\nDrowning out all my fears of the night\nOh delight in me\nLiving word show forth yourself \n",
            "image": null,
            "createdAt": "2025-11-27T10:48:44.576Z",
            "updatedAt": "2025-11-27T10:48:44.576Z",
            "mainArtiste": {
                "id": 3,
                "name": "Tito Pelumi"
            },
            "album": {
                "id": 2,
                "name": "Here I Am"
            },
            "featuredArtistes": [
                {
                    "id": 1,
                    "name": "John Kenny"
                }
            ]
        }
    }
}

Country Data API

Ameh Mathias Ejeh — Sun, 26 Oct 2025 19:55:55 +0000

A RESTful API that fetches country data from external APIs, stores it in a MySQL database, and provides CRUD operations with caching support.

Features

Fetch country data from REST Countries API
Fetch exchange rates from Open Exchange Rates API
Calculate estimated GDP for each country
Cache data in MySQL database
Filter and sort countries by region, currency, and GDP
Generate summary images with top countries
Full CRUD operations
Comprehensive error handling

Installation

Clone the repository

git clone https://github.com/ameh0429/country-api.git
cd country-api

Install dependencies

npm install axios canvas dotenv express mysql2

Set up environment variables

Create a .env file in the root directory:

PORT=3000
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=yourpassword
DB_NAME=countries_db
DB_PORT=3306

Create the MySQL database

CREATE DATABASE countries_db;

Start the server

npm start

For development with auto-reload:

npm run dev

The server will automatically create the necessary tables on startup.

API Endpoints

1. Refresh Country Data

Fetch fresh data from external APIs and update the database.

Request:

POST /api/countries/refresh

Response:

{
  "message": "Countries data refreshed successfully",
  "total_countries": 250,
  "last_refreshed_at": "2025-10-22T18:00:00.000Z"
}

2. Get All Countries

Retrieve all countries with optional filters.

Request:

GET /api/countries
GET /api/countries?region=Africa
GET /api/countries?currency=NGN
GET /api/countries?sort=gdp_desc

Query Parameters:

region - Filter by region (e.g., Africa, Europe, Asia)
currency - Filter by currency code (e.g., NGN, USD, EUR)
sort - Sort results:
- gdp_desc - Sort by GDP descending
- gdp_asc - Sort by GDP ascending
- population_desc - Sort by population descending
- population_asc - Sort by population ascending

Response:

[
  {
    "id": 1,
    "name": "Nigeria",
    "capital": "Abuja",
    "region": "Africa",
    "population": 206139589,
    "currency_code": "NGN",
    "exchange_rate": 1600.23,
    "estimated_gdp": 25767448125.2,
    "flag_url": "https://flagcdn.com/ng.svg",
    "last_refreshed_at": "2025-10-22T18:00:00Z"
  }
]

3. Get Single Country

Retrieve a specific country by name.

Request:

GET /api/countries/Nigeria

Response:

{
  "id": 1,
  "name": "Nigeria",
  "capital": "Abuja",
  "region": "Africa",
  "population": 206139589,
  "currency_code": "NGN",
  "exchange_rate": 1600.23,
  "estimated_gdp": 25767448125.2,
  "flag_url": "https://flagcdn.com/ng.svg",
  "last_refreshed_at": "2025-10-22T18:00:00Z"
}

4. Delete Country

Delete a country record from the database.

Request:

DELETE /api/countries/Nigeria

Response:

{
  "message": "Country deleted successfully"
}

5. Get Status

Get API statistics and last refresh timestamp.

Request:

GET /api/status

Response:

{
  "total_countries": 250,
  "last_refreshed_at": "2025-10-22T18:00:00.000Z"
}

6. Get Summary Image

Retrieve the generated summary image showing top countries by GDP.

Request:

GET /api/countries/image

Response: PNG image file

Error Responses

404 Not Found

{
  "error": "Country not found"
}

400 Bad Request

{
  "error": "Validation failed",
  "details": {
    "currency_code": "is required"
  }
}

503 Service Unavailable

{
  "error": "External data source unavailable",
  "details": "Could not fetch data from REST Countries API"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Data Schema

Country Fields

Field	Type	Required	Description
id	INT	Auto	Primary key
name	VARCHAR(255)	Yes	Country name
capital	VARCHAR(255)	No	Capital city
region	VARCHAR(100)	No	Geographic region
population	BIGINT	Yes	Population count
currency_code	VARCHAR(10)	Yes*	Currency code (e.g., NGN)
exchange_rate	DECIMAL(20,6)	No	Exchange rate to USD
estimated_gdp	DECIMAL(30,2)	No	Calculated GDP estimate
flag_url	TEXT	No	URL to country flag
last_refreshed_at	TIMESTAMP	Auto	Last update timestamp

*Note: currency_code can be null if country has no currency data

GDP Calculation

estimated_gdp = (population × random(1000-2000)) ÷ exchange_rate

A new random multiplier is generated on each refresh for each country.

Project Structure

country-api/
├── src/
│   ├── config/
│   │   └── database.js          # Database connection and initialization
│   ├── controllers/
│   │   └── countryController.js # Request handlers
│   ├── models/
│   │   └── countryModel.js      # Database queries
│   ├── routes/
│   │   └── countryRoutes.js     # API routes
│   ├── services/
│   │   ├── externalApiService.js # External API calls
│   │   └── imageService.js      # Image generation
│   ├── middleware/
│   │   ├── validation.js        # Input validation
│   │   └── errorHandler.js      # Error handling
│   └── server.js                # Main application entry
├── cache/
│   └── summary.png              # Generated summary image
├── .env                         # Environment variables
├── .env.example                 # Environment template
├── package.json                 # Dependencies
└── README.md                    # Documentation

External APIs Used

REST Countries API
- URL: https://restcountries.com/v2/all?fields=name,capital,region,population,flag,currencies
- Purpose: Fetch country information
Open Exchange Rates API
- URL: https://open.er-api.com/v6/latest/USD
- Purpose: Fetch currency exchange rates

Currency Handling Logic

Multiple Currencies

If a country has multiple currencies, only the first currency code from the array is stored.

No Currencies

If a country has no currencies:

currency_code: null
exchange_rate: null
estimated_gdp: 0
Country is still stored in database

Currency Not Found in Exchange API

If the currency code is not found in exchange rates:

exchange_rate: null
estimated_gdp: null
Country is still stored in database

Environment Variables

All configuration is done via .env file:

PORT: Server port (default: 3000)
DB_HOST: country-service-amehmathiasejeh.f.aivencloud.com
DB_USER: MySQL username
DB_PASSWORD: MySQL password
DB_NAME: defaultdb
DB_PORT: 10648

Error Handling

The API includes comprehensive error handling:

External API failures: Returns 503 with details
Database errors: Returns 500
Validation errors: Returns 400 with field details
Not found errors: Returns 404
All errors return JSON responses

Performance Considerations

Database indexing: Indexes on name, region, and currency_code
Connection pooling: MySQL connection pool with 10 connections
Caching: All country data is cached in database
Timeout handling: 10-second timeout on external API calls

View the Github Link

App is live at Country API

String Analysis RESTful API

Ameh Mathias Ejeh — Sun, 26 Oct 2025 18:45:41 +0000

A modular Node.js/Express API service that analyzes strings and stores their computed properties.

Features

String analysis with multiple computed properties
SHA-256 based unique identification
RESTful API endpoints
Query filtering with standard parameters
Natural language query parsing
In-memory storage (easily replaceable with database)
Comprehensive error handling

Project Structure

src/
├── index.js                          # Server entry point
├── app.js                            # Express app configuration
├── controllers/
│   └── stringController.js           # Request handlers
├── services/
│   ├── stringAnalyzer.js             # String analysis logic
│   ├── stringService.js              # Business logic layer
│   └── naturalLanguageParser.js      # NL query parser
├── repositories/
│   └── stringRepository.js           # Data access layer
├── routes/
│   └── stringRoutes.js               # Route definitions
└── middleware/
    ├── validation.js                 # Request validation
    └── errorHandler.js               # Error handling

Installation

npm install express

Running the Server

// Production mode
npm start

// Development mode with auto-reload
npm run dev

Server runs on http://localhost:3000.

API Endpoints

Create/Analyze String

POST /strings

Request:

{
  "value": "ameh mathias"
}

Response (201 Created):

Error Responses:

400 Bad Request - Invalid request body or missing "value" field
422 Unprocessable Entity - Invalid data type for "value" (must be string)
409 Conflict - String already exists

Get Specific String

GET /strings/{string_value}

Example: GET /strings/ameh%20mathias

Response (200 OK):

Error Response:

404 Not Found - String does not exist

Get All Strings with Filtering

GET /strings Query Parameters:
is_palindrome - boolean (true/false)
min_length - integer (minimum string length)
max_length - integer (maximum string length)
word_count - integer (exact word count)
contains_character - string (single character)

Example: GET /strings?is_palindrome=true&min_length=3&word_count=1

Response (200 OK):

Error Response:

400 Bad Request - Invalid query parameter values or types

Natural Language Filtering

GET /strings/filter-by-natural-language?query={natural_language_query}

Supported Query Patterns:

"all single word palindromic strings"
"strings longer than 10 characters"
"palindromic strings that contain the first vowel"
"strings containing the letter z"
"two word strings"
"strings between 5 and 20 characters"

Example: GET /strings/filter-by-natural-language?query=all%20single%20word%20palindromic%20strings

Response (200 OK):

{
    "data": [
        {
            "id": "31db973d2a73423e4a95ad7d5e9eed9d0a8e06c77ce7cb0c6f3b0d35b7f90625",
            "value": "ameh mathias",
            "properties": {
                "length": 12,
                "is_palindrome": false,
                "unique_characters": 8,
                "word_count": 2,
                "sha256_hash": "31db973d2a73423e4a95ad7d5e9eed9d0a8e06c77ce7cb0c6f3b0d35b7f90625",
                "character_frequency_map": {
                    "a": 3,
                    "m": 2,
                    "e": 1,
                    "h": 2,
                    " ": 1,
                    "t": 1,
                    "i": 1,
                    "s": 1
                }
            },
            "created_at": "2025-10-20T13:21:56.057Z"
        }
    ],
    "count": 1,
    "interpreted_query": {
        "original": "{natural_language_query}",
        "parsed_filters": {}
    }
}

Error Responses:

400 Bad Request - Unable to parse natural language query
422 Unprocessable Entity - Query parsed but resulted in conflicting filters

Delete String

DELETE /strings/{string_value}

Example: DELETE /strings/ameh%20mathias

Response:
204 No Content (empty body)

Error Response:

404 Not Found - String does not exist

String Properties

Each analyzed string includes:

Property	Type	Description
`length`	integer	Number of characters in the string
`is_palindrome`	boolean	Whether string reads the same forwards/backwards (case-insensitive)
`unique_characters`	integer	Count of distinct characters
`word_count`	integer	Number of words separated by whitespace
`sha256_hash`	string	SHA-256 hash for unique identification
`character_frequency_map`	object	Character-to-count mapping

Testing Examples

Using Postman

# Create a string
POST http://localhost:3000/strings \
  -H "Content-Type: application/json" \
  -d '{"value": "racecar"}'

# Get a string
http://localhost:3000/strings/ameh%20mathias

# Get palindromes
"http://localhost:3000/strings?is_palindrome=true"

# Natural language query
"http://localhost:3000/strings/filter-by-natural-language?query=single%20word%20palindromic%20strings"

# Delete a string
DELETE http://localhost:3000/strings/ameh%20mathias

Common status codes:

400 - Bad Request (invalid input)
404 - Not Found (resource doesn't exist)
409 - Conflict (duplicate resource)
422 - Unprocessable Entity (invalid data type)
500 - Internal Server Error

View the Github Link

App is live at String Analysis API

Profile API with Cat Facts

Ameh Mathias Ejeh — Wed, 15 Oct 2025 21:56:30 +0000

A simple RESTful API built with Node.js/Express that returns profile information along with dynamic cat facts.

Features

Profile endpoint at /me
Dynamic cat facts from external API
UTC timestamps in ISO 8601 format
Graceful error handling with fallback
Configurable timeout (5 seconds)
CORS enabled
Environment variable configuration
Request logging

Prerequisites

Node.js 18.x or higher
npm

Project Setup

├── app.js            # Main application file
├── package.json      # Project dependencies and scripts
├── .env.example      # Environment variables template
├── .env              # environment variables (git-ignored)
└── README.md         # Documentation

Installation

Clone or create the project directory
Install dependencies

npm install

Configure environment variables

cp.env.example .env

Edit .env file with your information

   PORT=8000
   USER_EMAIL=yourname@example.com
   USER_NAME=Your Full Name
   USER_STACK=Node.js/Express

Usage

Start the server

Production mode:

npm start

Development mode

npm run dev

The server will start on http://localhost:8000

API Endpoints

GET /me
Returns profile information with a dynamic cat fact.
Response (Success - 200):

Response (Error - 503):

{
  "status": "error",
  "user": {
    "email": "your.email@example.com",
    "name": "Your Full Name",
    "stack": "Node.js/Express"
  },
  "timestamp": "2025-10-15T14:30:45.123Z",
  "fact": "Cat fact temporarily unavailable. Did you know cats spend 70% of their lives sleeping?",
  "error": "Unable to fetch cat fact from external API"
}

GET /health
Health check endpoint.
Response (200):

Testing

Test the endpoint using postman:

// Test profile endpoint
http://localhost:8000/me

// Test health check
http://localhost:8000/health

Error Handling

The API handles the following error scenarios:

Network errors: Returns 503 with fallback message
Timeout (5s): Returns 503 with fallback message
External API failure: Returns 503 with fallback message
Invalid routes: Returns 404 with error message
Server errors: Returns 500 with error message

Link

View the Live Link
View the Github Link

Task Manager API

Ameh Mathias Ejeh — Fri, 01 Aug 2025 09:46:17 +0000

A RESTful API for managing tasks built with Node.js and Express.
Repo

Features

CRUD operations for tasks
In-memory data storage
Status filtering
Pagination support
Modern ES6+ JavaScript
Comprehensive error handling
Request logging middleware

Task Entity

Each task has the following properties:

id (UUID) - Unique identifier
title (string) - Task title (required)
description (string) - Task description (optional)
status (enum) - One of: "pending", "in-progress", "completed"
createdAt (timestamp) - Creation timestamp
updatedAt (timestamp) - Last update timestamp

API Endpoints

Get All Tasks

GET /api/tasks

Query parameters:

status - Filter by status (pending, in-progress, completed)
page - Page number for pagination (default: 1)
limit - Number of items per page (default: 10)

Example: GET /api/tasks?status=completed&page=1&limit=5

Get Task by ID

GET /api/tasks/:id

Create New Task

POST /api/tasks
Content-Type: application/json

{
  "title": "Complete project",
  "description": "Finish the task manager API",
  "status": "pending"
}

Update Task

PUT /api/tasks/:id
Content-Type: application/json

{
  "title": "Updated title",
  "description": "Updated description",
  "status": "in-progress"
}

Delete Task

DELETE /api/tasks/:id

Installation & Setup

Prerequisites: Ensure you have Node.js installed
Install dependencies:

   npm install

Run the server:

   # Production mode
   npm start

   # Development mode with auto-restart
   npm run dev

Server will start on: http://localhost:3000

Project Structure

task-manager-api/
│   ├── controllers/
│   │   └── taskController.js
│   ├── middleware/
│   │   ├── errorHandler.js
│   │   └── logger.js
│   ├── models/
│   │   └── Task.js
│   ├── routes/
│   │   └── taskRoutes.js
│   ├── services/
│   │   └── taskService.js
│   ├── utils/
│   │   └── validation.js
│   └── server.js
├── .gitignore
├── .env
├── package.json
└── README.md

Example Usage

Create a task

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn Node.js", "description": "Complete Node.js tutorial", "status": "pending"}'

List all tasks

curl http://localhost:3000/api/tasks

Filter completed tasks with pagination

curl "http://localhost:3000/api/tasks?status=completed&page=1&limit=5"

Update a task

curl -X PUT http://localhost:3000/api/tasks/{task-id} \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

Delete a task

curl -X DELETE http://localhost:3000/api/tasks/{task-id}

Status Codes

200 - Success
201 - Created
400 - Bad Request
404 - Not Found
500 - Internal Server Error

Error Response Format

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

Conclusion

The API includes sample data and comprehensive logging so you can immediately test all endpoints. This README provides detailed usage examples with curl commands for testing each endpoint.
The code is production-ready with proper error handling, validation, and follows REST API design principles throughout.

Future Improvements

Implement user route and authentication.
Connect to a database for persistent storage.
Generate API docs using Swagger UI
Deploy the API to Render, Railway, Heroku or AWS

Author

Ameh Mathias Ejeh LinkedIn • GitHub

Todo List Backend API

Ameh Mathias Ejeh — Mon, 28 Jul 2025 17:58:34 +0000

A comprehensive, production-ready REST API for a Todo List application built with Node.js, Express, MongoDB, and ECMAScript Modules (ESM). Features include JWT authentication, task management with advanced filtering, email notifications, and user profile management.

Features

JWT-based Authentication - Secure user authentication with token-based sessions
Complete Task Management - CRUD operations with advanced filtering and search
Email Notifications - Task creation confirmations and daily reminders
User Profile Management - Update name, email, and password
Advanced Filtering - Filter tasks by completion status, priority, due date, and search terms
Pagination - Efficient handling of large task lists
Security Features - Rate limiting, CORS, helmet protection
Input Validation - Comprehensive request validation using express-validator
RESTful Design - Clean, intuitive API endpoints

Technology Stack

Runtime: Node.js with ECMAScript Modules (ESM)
Framework: Express.js
Database: MongoDB with Mongoose ODM
Authentication: JWT (JSON Web Tokens)
Password Hashing: bcryptjs
Email Service: Nodemailer
Validation: express-validator
Scheduling: node-cron (for daily reminders)
Security: cors, express-rate-limit

Project Structure

todo-backend-api/
├── server.js                 # Main server file
├── package.json              # Dependencies and scripts
├── .env                      # Environment variables
├── README.md                 # API documentation
├── controllers/
│   ├── authController.js     # Authentication logic
│   └── taskController.js     # Task management logic
├── models/
│   ├── User.js              # User data model
│   └── Task.js              # Task data model
├── middleware/
│   ├── authMiddleware.js    # JWT authentication middleware
│   ├── errorMiddleware.js   # Global error handling
│   └── validationMiddleware.js # Input validation rules
├── routes/
│   ├── authRoutes.js        # Authentication routes
│   └── taskRoutes.js        # Task management routes
├── services/
│   └── emailService.js      # Email notification service
└── utils/
    ├── generateToken.js     # JWT token generation
    └── responseHandler.js   # Standardized API responses

The API will be available at http://todo-list-application.up.railway.app

API Documentation

Base URL

http://todo-list-application.up.railway.app/api

Response Format

All API responses follow this standardized format:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data (when applicable)
  }
}

Authentication Endpoints

Register User

Create a new user account.
Endpoint: POST /api/register
Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123"
}

Success Response (201):

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "name": "John Doe",
      "email": "john@example.com",
      "createdAt": "2023-11-20T10:30:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Error Response (400):

{
  "success": false,
  "message": "User with this email already exists"
}

Login User

Authenticate an existing user.
Endpoint: POST /api/login
Request Body:

{
  "email": "john@example.com",
  "password": "password123"
}

Success Response (200):

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "name": "John Doe",
      "email": "john@example.com",
      "createdAt": "2023-11-20T10:30:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Update Profile

Update user's profile information.
Endpoint: PUT /api/profile
Authentication: Required (Bearer Token)
Request Body:

{
  "name": "John Smith",
  "email": "johnsmith@example.com",
  "password": "newpassword123"
}

Success Response (200):

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "user": {
      "id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "name": "John Smith",
      "email": "johnsmith@example.com",
      "updatedAt": "2023-11-20T11:00:00.000Z"
    }
  }
}

Task Management Endpoints

Create Task

Create a new task and send confirmation email.
Endpoint: POST /api/tasks
Authentication: Required (Bearer Token)
Request Body:

{
  "title": "Complete project documentation",
  "description": "Write comprehensive API documentation for the todo app",
  "dueDate": "2023-11-25T15:30:00.000Z",
  "priority": "High"
}

Success Response (201):

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "task": {
      "_id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "title": "Complete project documentation",
      "description": "Write comprehensive API documentation for the todo app",
      "dueDate": "2023-11-25T15:30:00.000Z",
      "priority": "High",
      "isCompleted": false,
      "userId": "60f7b3b3b3b3b3b3b3b3b3b3",
      "createdAt": "2023-11-20T10:30:00.000Z",
      "updatedAt": "2023-11-20T10:30:00.000Z"
    }
  }
}

Get All Tasks

Retrieve tasks with optional filtering, searching, and pagination.
Endpoint: GET /api/tasks
Authentication: Required (Bearer Token)
Query Parameters:

isCompleted (boolean): Filter by completion status
priority (string): Filter by priority (Low, Medium, High)
dueDate (string): Filter by due date (YYYY-MM-DD format)
search (string): Search in title and description
page (integer): Page number for pagination (default: 1)
limit (integer): Number of items per page (default: 10, max: 100)
sortBy (string): Sort field (default: createdAt)
sortOrder (string): Sort order - asc or desc (default: desc)

Example Request:

GET /api/tasks?isCompleted=false&priority=High&page=1&limit=5&search=project

Success Response (200):

{
  "success": true,
  "message": "Tasks retrieved successfully",
  "data": {
    "tasks": [
      {
        "_id": "60f7b3b3b3b3b3b3b3b3b3b3",
        "title": "Complete project documentation",
        "description": "Write comprehensive API documentation",
        "dueDate": "2023-11-25T15:30:00.000Z",
        "priority": "High",
        "isCompleted": false,
        "userId": "60f7b3b3b3b3b3b3b3b3b3b3",
        "createdAt": "2023-11-20T10:30:00.000Z",
        "updatedAt": "2023-11-20T10:30:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 3,
      "totalTasks": 15,
      "hasNextPage": true,
      "hasPrevPage": false,
      "limit": 5
    }
  }
}

Get Single Task

Retrieve a specific task by ID.
Endpoint: GET /api/tasks/:id
Authentication: Required (Bearer Token)
Success Response (200):

{
  "success": true,
  "message": "Task retrieved successfully",
  "data": {
    "task": {
      "_id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "title": "Complete project documentation",
      "description": "Write comprehensive API documentation",
      "dueDate": "2023-11-25T15:30:00.000Z",
      "priority": "High",
      "isCompleted": false,
      "userId": "60f7b3b3b3b3b3b3b3b3b3b3",
      "createdAt": "2023-11-20T10:30:00.000Z",
      "updatedAt": "2023-11-20T10:30:00.000Z"
    }
  }
}

Update Task

Update an existing task.
Endpoint: PUT /api/tasks/:id
Authentication: Required (Bearer Token)
Request Body:

{
  "title": "Updated task title",
  "description": "Updated description",
  "dueDate": "2023-11-26T15:30:00.000Z",
  "priority": "Medium",
  "isCompleted": true
}

Success Response (200):

{
  "success": true,
  "message": "Task updated successfully",
  "data": {
    "task": {
      "_id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "title": "Updated task title",
      "description": "Updated description",
      "dueDate": "2023-11-26T15:30:00.000Z",
      "priority": "Medium",
      "isCompleted": true,
      "completedAt": "2023-11-20T12:00:00.000Z",
      "userId": "60f7b3b3b3b3b3b3b3b3b3b3",
      "createdAt": "2023-11-20T10:30:00.000Z",
      "updatedAt": "2023-11-20T12:00:00.000Z"
    }
  }
}

Delete Task

Delete a specific task.
Endpoint: DELETE /api/tasks/:id
Authentication: Required (Bearer Token)
Success Response (200):

{
  "success": true,
  "message": "Task deleted successfully"
}

Email Notifications

Task Creation Confirmation

Automatically sent when a new task is created. Contains task details and encouragement message.

Daily Reminders

Automatically sent at 9:00 AM UTC to users who have tasks due the next day. Uses node-cronfor scheduling.

Email Content Includes:

List of tasks due tomorrow
Task titles, descriptions, and priorities
Color-coded priority indicators
Professional HTML formatting

Authentication

All protected endpoints require a JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Token Structure:

Expires in 7 days (configurable)
Contains user ID in payload
Signed with JWT_SECRET from environment variables

Error Handling

Common Error Responses

Validation Error (400):

{
  "success": false,
  "message": "Title must be between 1 and 100 characters"
}

Authentication Error (401):

{
  "success": false,
  "message": "Access denied. No token provided."
}

Not Found Error (404):

{
  "success": false,
  "message": "Task not found"
}

Server Error (500):

{
  "success": false,
  "message": "Server error during task creation"
}

Input Validation

User Registration

name: 2-50 characters, trimmed
email: Valid email format, lowercase, unique
password: Minimum 6 characters

Task Creation/Update

title: 1-100 characters, required, trimmed
description: Optional, max 500 characters, trimmed
priority: Must be "Low", "Medium", or "High"
dueDate: Must be valid ISO 8601 date, future dates only
isCompleted: Boolean value

Security Features

Rate Limiting

100 requests per 15 minutes per IP address
Applied to all /api/* routes

Password Security

Hashed using bcryptjs with salt rounds of 12
Never returned in API responses
Comparison using secure bcrypt.compare()

CORS Protection

Configurable allowed origins
Credentials support enabled

Database Schema

User Collection

{
  _id: ObjectId,
  name: String (required, 2-50 chars),
  email: String (required, unique, lowercase),
  password: String (required, hashed, min 6 chars),
  createdAt: Date,
  updatedAt: Date
}

Task Collection

{
  _id: ObjectId,
  title: String (required, 1-100 chars),
  description: String (optional, max 500 chars),
  dueDate: Date (optional, future dates only),
  priority: String (enum: Low/Medium/High, default: Medium),
  isCompleted: Boolean (default: false),
  completedAt: Date (set when completed),
  userId: ObjectId (required, references User),
  createdAt: Date,
  updatedAt: Date
}

Database Indexes

userId + createdAt (compound index for efficient task queries)
userId + isCompleted (for filtering completed tasks)
userId + priority (for priority filtering)
dueDate (for reminder email queries)

Deployment

Environment Variables for Production

NODE_ENV=production
PORT=3000
MONGODB_URI=mongodb://your-production-mongodb-uri
JWT_SECRET=your-very-secure-production-jwt-secret
JWT_EXPIRE=7d

# Production Email Service (replace with your SMTP provider)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-specific-password
EMAIL_FROM=noreply@yourdomain.com

# Frontend URL for CORS
FRONTEND_URL=https://your-frontend-domain.com

Contact Book App

Ameh Mathias Ejeh — Mon, 28 Jul 2025 15:28:28 +0000

Project Overview

This is a console-based application that allows users to manage a basic contact list. It leverages Python's dictionary data structure to store contact names and their corresponding phone numbers. The application provides a menu-driven interface for adding new contacts, looking up existing ones, listing all stored contacts, and deleting contacts.

Features

Add Contact: Allows users to input a contact's name and phone number, which are then stored in the contact book.
Look Up Contact: Users can search for a contact by name, and if found, the application displays their phone number. It handles cases where the contact does not exist.
List All Contacts: Displays all stored contact names and their phone numbers in an easy-to-read format. It also informs the user if the contact book is empty.
Delete Contact: Provides the ability to remove an existing contact from the book by name. It includes checks for an empty book and for contacts not found.
Menu-Driven Interface: Guides the user through options with clear prompts.
Continuous Operation: Runs in a loop, allowing multiple operations until the user chooses to exit.

How to Use

Prerequisites

Python 3.x installed on your system.

Running the Application

Save the code: Save the provided Python code into a file named contact_book.py (or any other .py extension).
Open a terminal/command prompt: Navigate to the directory where you saved contact_book.py.
Run the script: Execute the command:

python contact_book.py

Interacting with the App

Upon running, you will see the main menu:

--- Simple Contact Book Menu ---
1. Add a new contact
2. Look up a contact
3. List all contacts
4. Delete a contact
5. Exit
Enter your choice (1-5):

To Add a New Contact (Option 1):
- Enter 1and press Enter.
- Follow the prompts to enter the contact's name and phone number.
- A confirmation message will be displayed.
To Look Up a Contact (Option 2):
- Enter 2and press Enter.
- Enter the name of the contact you wish to find.
- The app will display the contact's phone number or indicate if the contact is not found.
To List All Contacts (Option 3):
- Enter 3and press Enter.
- The app will display all contacts stored in the book, or a message if the book is empty.
To Delete a Contact (Option 4):
- Enter 4and press Enter.
- The app will first list current contacts for reference.
- Enter the name of the contact you wish to delete.
- A confirmation message will be displayed if successful, or a "not found" message if the contact doesn't exist.
To Exit the App (Option 5):
- Enter 5and press Enter.
- The app will print a goodbye message and terminate.
Invalid Choice: If you enter any number or text that is not a valid menu option, the app will prompt you to try again.

Code Structure

The application's logic is contained within a single Python script (contact_book.py) and is structured as follows:

contacts = {}: An empty Python dictionary initialized at the beginning. This dictionaryis the core data structure, storing name: phone_number pairs.
while True: loop: The primary loop that keeps the application running, continuously presenting the menu and processing user input until an explicit exit command.
Menu Display: print() statements inside the loop present the user with the available options.
User Input: input() captures the user's menu choice.
Conditional Logic (if/elif/else):
- if choice == '1': Handles adding a contact. It takes nameand phone_number input and adds them to the contactsdictionary using contacts[name] = phone_number.
- elif choice == '2': Handles looking up a contact. It takes a nameas input and uses the inoperator (if name in contacts:) to check for the key's existence before attempting to retrieve and print its value (contacts[name]).
- elif choice == '3': Handles listing all contacts. It checks if the contactsdictionary is empty (len(contacts) == 0 or if not contacts:). If not empty, it iterates through all key-value pairs using for name, number in contacts.items(): and prints them.
- elif choice == '4': Handles deleting a contact. It first checks if the dictionary is empty. If not, it prompts for a name to delete, checks if the name exists using in, and then uses del contacts[name_to_delete] to remove the entry. Provides feedback for success or if the contact is not found.
- elif choice == '5': Handles exiting the app. It prints a goodbye message and uses breakto terminate the whileloop.
- else: Catches invalid menu choices.

Key Concepts Demonstrated

This project effectively utilizes and reinforces the following fundamental Python programming concepts:

Data Structures: Extensive use of Dictionaries (dict) for storing and managing key-value pairs (contacts).
- Dictionary methods like .items().
- Dictionary operations like adding/updating (dict[key] = value), accessing (dict[key]), and deleting (del dict[key]).
- Checking for key existence using the inoperator.
Variables: Storing names, phone numbers, user choices, and the contacts dictionary.
Input/Output: Using input() for user interaction and print() for displaying information.
Logic & Control Flow:
- whileLoop: For the continuous operation of the application.
- if/elif/else Statements: For decision-making based on user menu choices and dictionary conditions.
- forLoop: For iterating through dictionary items to display all contacts.
- breakKeyword: For gracefully exiting the main application loop.
String Formatting: Using f-strings (f"...") for clear and dynamic output messages.

Number Guessing Game

Ameh Mathias Ejeh — Fri, 11 Jul 2025 22:28:42 +0000

Project Overview

This is a simple console-based number guessing game implemented in Python. The computer "thinks" of a random number within a specified range (1 to 100), and the player's goal is to guess that number. The game provides hints ("Too high!" or "Too low!") after each guess, helping the player narrow down the possibilities. The game tracks and displays the number of attempts it took to guess the correct number.

Features

Random Number Generation: The computer selects a random integer between 1 and 100 (inclusive) as the secret number.
Interactive Guessing: Players can repeatedly enter their guesses.
Hints System: Provides feedback to the player after each guess, indicating whether their guess was too high or too low.
Guess Counter: Keeps track of the number of attempts the player makes.
Win Condition: The game ends once the player correctly guesses the secret number.
Summary: Displays the total number of guesses taken and the secret number upon winning.
Input Validation: Handles non-numeric input gracefully, prompting the user to enter a valid number.

How to Play

Prerequisites

Python 3.x installed on your system.

Running the Game

Save the code: Save the provided Python code into a file named guessing_game.py (or any other .py extension).
Open a terminal/command prompt: Navigate to the directory where you saved guessing_game.py.
Run the script: Execute the command:

python guessing_game.py

Game Instructions

Upon starting, the game will welcome you and inform you that it has chosen a number between 1 and 100.
You will be prompted to Enter your guess: .
Type a whole number between 1 and 100 and press Enter.
Hints:
- If your guess is too high, the game will say: "Too high! Try a lower number!"
- If your guess is too low, the game will say: "Too low! Try a higher number!"
Winning:
- If your guess is correct, the game will congratulate you and tell you how many guesses it took to find the number.
- The game will then end.
Invalid Input: If you enter anything that is not a whole number (e.g., text, decimals), the game will prompt you to enter a valid number and will not count that as a guess.

Code Structure

The game's logic is contained within a single Python script (guessing_game.py) and follows this structure:

import random: Imports the random module, which is essential for generating the secret_number.
secret_number = random.randint(1, 100): This line generates the random target number for the game. For testing purposes during development, you might temporarily print(secret_number) but it should be removed or commented out for actual gameplay.
guesses = 0: An integer variable initialized to zero, used to count the player's attempts.
while True: loop: This is the main game loop. It continues indefinitely until the player guesses correctly and a break statement is executed.
try-except ValueError block: Encapsulates the user input process.
- try: Attempts to get user input (input()) and convert it to an integer (int()).
- except ValueError: Catches errors if the user enters non-numeric text, printing an error message and allowing the loop to continue without crashing.
guesses += 1: Increments the guesses counter with each valid attempt.
if/elif/else statements: These conditional statements form the core game logic:
- if user_guess > secret_number: Provides the "Too high!" hint.
- elif user_guess < secret_number: Provides the "Too low!" hint.
- else: This block is executed when user_guess == secret_number. It congratulates the player, prints the total guesses, and then uses breakto exit the whileloop, ending the game.

Key Concepts Demonstrated

This project effectively demonstrates and reinforces the following Python programming concepts:

Modules: Importing and using the randommodule.
Variables: Storing the secret_number, user_guess, and guessescount.
Input/Output: Using input() to get user guesses and print() to provide game feedback.
Logic & Control Flow:
- while Loop:For repetitive guessing until a condition is met.
- if/elif/else Statements: For decision-making based on guess comparison.
- breakKeyword: For exiting the game loop early upon a win.
Type Conversion: Using int() to convert string input to an integer.
Counters: Incrementing a variable to track progress.
Error Handling: Basic try-except for ValueError to handle invalid input.

Note: Check out the repo here

Basic To-Do List App

Ameh Mathias Ejeh — Fri, 11 Jul 2025 14:01:11 +0000

Project Overview

This is a simple console-based To-Do List application built in Python. It allows users to manage their daily tasks by providing options to add new tasks, view existing tasks, and remove completed or unwanted tasks. The application runs in a continuous loop until the user decides to exit.

Features

Add Task: Allows the user to input a new task and add it to their to-do list.
View Tasks: Displays all current tasks in a numbered list, making it easy to reference. It also informs the user if the list is empty.
Remove Task: Enables the user to remove a task by specifying its corresponding number from the displayed list. Includes error handling for invalid input (non-numeric input or out-of-range numbers).
Exit Application: Provides an option to gracefully terminate the program.
User-Friendly Interface: Presents a clear menu and provides feedback for all operations.

How to Use

Prerequisites

Python 3.x installed on your system.

Running the Application

Save the code: Save the provided Python code into a file named todo_app.py (or any other .py extension).
Open a terminal/command prompt: Navigate to the directory where you saved todo_app.py.
Run the script: Execute the command:

python todo_app.py

Interacting with the App

Upon running, you will see a main menu:
Welcome to the To-Do App!

1. Add a task
2. View tasks
3. Remove a task
4. Exit the app
Enter your choice (1-4):

To Add a Task:

Enter 1and press Enter.
You will be prompted: Enter the task you want to add:
Type your task (e.g., Go grocery shopping) and press Enter.
The app will confirm the task has been added.

Note: Each time you choose '1', you add one task.

To View Tasks:

Enter 2and press Enter.
The app will display your current tasks as a numbered list (e.g., 1. Go grocery shopping).
If no tasks are present, it will inform you.

To Remove a Task:

Enter 3and press Enter.
The app will first show you your current tasks with their numbers.
You will be prompted: Enter the task number you want to remove:
Enter the number corresponding to the task you wish to remove (e.g., 1) and press Enter.
The app will confirm the task has been removed.
Error Handling: If you enter invalid input (e.g., text, a number outside the range of tasks), the app will provide an error message and return to the main menu.

To Exit the App:

Enter 4and press Enter.
The app will print a goodbye message and close.

Code Structure

The application's logic is primarily contained within a single Python script (todo_app.py) and is structured as follows:

to_do_items = []: An empty Python listis initialized at the beginning of the script. This list serves as the central data storage for all active tasks.
while True: loop: The core of the application is an infinite whileloop. This ensures the menu is continuously displayed and the user can perform multiple actions until they explicitly choose to exit.
Menu Display: Inside the loop, print()statements are used to present the user with a clear set of options.
User Input: The input() function captures the user's choice (1-4).
Conditional Logic (if/elif/else): A series of if, elif (else if), and elsestatements are used to process the user's choice:

a. if choice == "1": Handles adding a task. It prompts for the task string and uses list.append() to add it.

b. elif choice == "2": Handles viewing tasks. It checks if the list is empty (len()) and, if not, uses a for loop with enumerate(..., start=1) to display tasks with user-friendly 1-based numbering.

c. elif choice == "3": Handles removing a task.

It first displays the current tasks.
It uses a try-except block to gracefully handle ValueError if the user enters non-numeric input.
It converts the user's 1-based input to a 0-based list index.
A critical if statement (0 <= actual_index_to_remove < len(to_do_items)) validates the index to prevent IndexError for out-of-range numbers.
If the index is valid, list.pop() is used to remove the task at that position.

d. elif choice == "4": Handles exiting the app by printing a goodbye message and using the break keyword to terminate the while loop.

e. else: Catches any invalid numerical or text input and prompts the user to try again.

Key Concepts Demonstrated

This project effectively utilizes and reinforces several fundamental Python programming concepts:

Variables: Storing user choices, tasks, and the to_do_items list.
Data Structures: Extensive use of Lists (to_do_items) for storing and managing collections of tasks.
Input/Output: Using input() to get data from the user and print() to display information and feedback.
Logic & Control Flow:

a. while Loops: For maintaining the application's running state.
b. if/elif/else Statements: For decision-making based on user choices and list conditions.
c. for Loops: For iterating over the to_do_items list to display tasks.

Functions/Methods:

a. Built-in functions like len(), int(), enumerate().
b. List methods like append() and pop().

String Formatting: Using f-strings (f"...") for clear and dynamic messages.
Error Handling: Basic try-except blocks to manage potential runtime errors (like ValueError for invalid input) and conditional checks for IndexError.

Note. Check out the repo here

The Importance of Leveraging AI to Learn

Ameh Mathias Ejeh — Tue, 24 Jun 2025 13:14:00 +0000

Artificial Intelligence (AI) refers to the development of computer systems capable of performing tasks that typically require human intelligence, such as reasoning, learning, decision-making, and perception. There's no doubt that AI is here to stay, and it is essential to leverage its capabilities appropriately in the learning process.

As a junior developer who is just beginning to learn how to code, it might not be wise to rely solely on AI to generate code. If you do, how will you truly learn? To effectively leverage AI, it's important to use it as a learning companion rather than a shortcut. Let it guide you, challenge your understanding, and support your growth, instead of simply handing you complete answers.

The quality of AI-generated responses depends heavily on the quality of the prompts you give it. To get meaningful and useful responses, follow these six building blocks of a good prompt:

Task: Begin with a clear action verb and define the specific output you’re expecting.
Context: Provide relevant background information or clarify the scenario to help the AI understand your needs.
Exemplars: Share examples to guide the AI in terms of format, tone, or content style.
Persona: Specify the role the AI should take—such as a coach, teacher, or technical expert—to align its tone and approach.
Format: Clearly define the desired output format—whether it’s a bullet list, essay, explanation, or report.
Tone: Decide on the emotional or professional tone you want—formal, friendly, motivational, etc.

By following this prompting framework, you'll greatly enhance your ability to communicate with AI and receive more accurate, detailed, and helpful responses. Use AI wisely—not as a replacement for learning, but as a powerful tool to support and accelerate your educational journey

Building a User Feedback Collector with Node.js and Express.js

Ameh Mathias Ejeh — Tue, 24 Jun 2025 11:07:38 +0000

Introduction

This project collects user feedback via a form and save it in a local file. A user feedback collector is a fundamental feature in many applications, it is a tool or system, used to gather feedback from users about their experience with a product or service. It helps project teams understand what users think, feel, or need, and is essential for making informed improvements.

Prerequisites

Basic knowledge of JavaScript, Node.js and Express.
Node.js, git and npm installed on your computer.

Features

Accepts feedback with name, email, message, and an image.
Validates all input fields, including email format and message length.
Accepts only .jpeg, .jpg, .png images up to 10MB.
Saves uploaded files to the /uploads folder.
Persists feedback in a local feedbacks.json file.

Project Structure

TC-Feedback-Collector/
├──controllers/       // Handles request logic
├──middleware/        // Custom middleware functions
├──model/
├──routes/            // API route definition
├──service/
├──utility/
├──app.js             // main application file
├──.gitignore         // gitignore file
├──package.json       // Project dependencies
└──README.md         //documentation file

Project setup

Clone the repository and navigate to the project directory

git clone https://github.com/Jerryemmanuel01/TC-Feedback-Collector.git
cd TC-Feedback-Collector

Initialize the project as a node.js project.

npm init -y

This will create a package.json file

Install dependencies

npm install express multer nodemon path

express: Simplifies the process of building web servers and APIs.
multer: Allows users to upload files via forms (e.g., images, documents).
nodemon: Automatically restarts the Node.js application when file changes are detected.
path: Provides utilities for working with file and directory paths in a way that is platform-independent.

1. Setting up the Server

This is the main server file app.js. It sets up an Express.js server, serves static files (uploaded images), routes feedback submissions to /feedback and also parses incoming JSON and URL-encoded form data.

2. Setting up `saveFeedback` file

The code defines a function that handles saving user feedback to a local JSON file (feedbacks.json) on the server.

3. Setting up the middleware

The middleware folder contains two files; fileUpload and validateFeedback files.

fileupload.js: This code sets up file upload handling in a Node.js application using the Multer middleware. It securely handles file uploads by saving them in a dedicated folder, naming them uniquely and enforcing file type and size restrictions.
validateFeedback.js: This code performs server-side validation on the feedback submission request before it's processed further. It ensures the submitted data is well-formed and meets specific rules

4. Creating the routes

This code sets up an Express.js route for handling user feedback submissions. The POST endpoint (/) validates incoming feedback data and saves the feedback to storage (JSON file)

5. Run the Application

npm run start

6. Testing the Application using Postman

/feedback is the main endpoint that accepts a feedback submission.

Enter the url

http://localhost:5000/feedback

Set the body type to form-data
Add the necessary key-value pairs

Key	Type	Value
name	Text	Samson
email	Text	testing@gmail.com
message	Text	Just testing this route
file	File	Image.jpg

Send the request. If all validations pass, you’ll get a success response like:

{
  "status": 201,
  "message": "Feedback saved successfully.",
  "error": false
}

Conclusion

This project is a simple yet effective solution for gathering structured user feedback along with image uploads. It demonstrates key backend development practices, including form validation, file handling with Multer, and structured routing in Express.js.

Contributors

Abdulmalik Hussein
Bright Bediako
Adeniyi Adebimpe
Adejumo David
Dominic Jerryemmanuel
Adekoya Adegbenga
Ameh Mathias Ejeh
Basit Adebayo
Daniel Kasambala

Forem: Ameh Mathias Ejeh

School Library System API

Table of Contents

Features

Tech Stack

Project Structure

Setup & Installation

Prerequisites

Steps

Environment Variables

API Documentation

Response Format

Pagination & Filtering (all GET list endpoints)

Authentication

POST /attendants/login

Authors

GET /authors

POST /authors 🔒

PUT /authors/:id 🔒

Books

GET /books

POST /books 🔒

POST /books/:id/borrow 🔒

POST /books/:id/return 🔒

Students

POST /students 🔒

GET /students/:id 🔒

Attendants

POST /attendants 🔒

Business Rules

Error Reference

Onebody API Documentation

Base URL: http://localhost:5000

Register

Login

Create Artiste (Protected)

Response

Get all Artistes

Response

Get Artiste by id

Response

Create Album (Protected)

Response

Get all Album

Response

Get Album by id

Response

Create Song (Protected)

Response

Get all Songs

Response

Get Song by id

Response

Country Data API

Features

Installation

Clone the repository

Install dependencies

Set up environment variables

Create the MySQL database

Start the server

API Endpoints

1. Refresh Country Data

2. Get All Countries

3. Get Single Country

4. Delete Country

5. Get Status

6. Get Summary Image

Error Responses

404 Not Found

400 Bad Request

503 Service Unavailable

500 Internal Server Error

Data Schema

Country Fields

GDP Calculation

Project Structure

External APIs Used

Currency Handling Logic

Multiple Currencies

POST `/attendants/login`

GET `/authors`

POST `/authors` 🔒

PUT `/authors/:id` 🔒

GET `/books`

POST `/books` 🔒

POST `/books/:id/borrow` 🔒

POST `/books/:id/return` 🔒

POST `/students` 🔒

GET `/students/:id` 🔒

POST `/attendants` 🔒

Base URL: `http://localhost:5000`