A robust and secure RESTful API for a blogging platform built with Express.js, TypeScript, and MongoDB. The codebase demonstrates modern backend practices including user authentication, role‑based access control, token management, validation, and structured logging.

• Authentication & Authorization – JWT‑based login/register with refresh tokens; role‑based access control (admin/user)
• User Management – endpoints for creating, updating, deleting, and fetching user profiles
• Access/Refresh Tokens – secure access tokens with expiration and persistent refresh tokens stored in HTTP‑only cookies and database
• Rate Limiting – prevents abuse with configurable limits
• Security Hardening – Helmet headers, CORS filtering, input validation
• Data Validation – express-validator schemas for requests and parameters
• Logging – Winston configured for JSON logs with levels and error stacks
• Environment Configuration – centralized .env support with sensible defaults
• API Versioning – v1 implemented; v2 scaffolding provided
• Hot‑Reload Development – Nodemon with ts-node for fast iteration
• TypeScript with Path Aliases – clean imports with @/ alias
• Graceful Shutdown – database disconnect on SIGTERM/SIGINT

• Node.js v16+
• npm v7+
• MongoDB (local or Atlas)

1. Clone the repo:

   git clone <repository-url>
   cd blog-api

2. Install dependencies:

   npm install

3. Create a .env file (see configuration section below).
4. Start development server:

   npm run dev

   Server listens on http://localhost:${PORT || 3000} by default.

Note: The .env.example file provides a template for required values.

Allowed origins are defined in config.WHITELIST_ORIGINS. Modify as needed.

To prevent unauthorized admin signups, only emails in WHITELIST_ADMIN_MAILS may register with role admin.

blog-api/
├── src/
│   ├── server.ts              # App entry point, middleware & routes setup
│   ├── config/                # Environment and application config
│   │   └── index.ts
│   ├── controllers/           # Route handlers grouped by version
│   │   └── v1/
│   │       ├── auth/          # register, login, refresh-token, logout
│   │       └── user/          # user CRUD and profile endpoints
│   ├── routes/
│   │   └── v1/                # Express routers for API v1
│   ├── middlewares/           # auth, authorization, validation
│   ├── models/                # Mongoose schemas (User, Token)
│   ├── validators/            # express-validator schemas
│   ├── lib/                   # shared utilities (jwt, mongoose, rate-limit, winston)
│   ├── utils/                 # helper functions (random username, etc.)
│   ├── @types/                # custom type declarations
│   └── ...                    # other support code
├── dist/                      # compiled output (ignored in git)
├── .env.example
├── nodemon.json
├── tsconfig.json
├── package.json
└── README.md

Base URL: http://localhost:<PORT>/api/v1

• limit (integer 1–50, default 20)
• offset (integer ≥0, default 0)

All endpoints use express-validator; invalid inputs return 400 ValidationError with detailed messages.

Access tokens are sent in Authorization: Bearer <token> header. Refresh tokens are stored in HTTP‑only cookies.

• user: basic access
• admin: can view/delete other users and list users

GET /
Returns basic status JSON { message, status, version, timestamp }.

• npm run dev – start server with hot reload
• npm run format – format source with Prettier
• npm run format:check – verify formatting

TypeScript is compiled on‑the‑fly via ts-node. To build manually:

npx tsc

• Helmet secures headers
• CORS whitelisting with origin logging
• Rate Limiting protects endpoints
• JWT & Cookies for session management
• Password Hashing with bcrypt
• Input Validation prevents malformed data
• Environment Isolation sensitive info kept in .env

• Winston configured for JSON output
• Console transport active in development
• Log levels controlled by LOG_LEVEL
• Errors include stack traces

• Consistent error codes (AuthenticationError, AuthorizationError, ValidationError, NotFound, ServerError)
• Database and startup errors are logged; server exits in production on startup failure.

• Follow TypeScript conventions
• Keep code properly typed
• Add appropriate unit tests (if present)
• Use clear commit messages
• Respect existing file headers and license

Apache License 2.0 – see LICENSE.

Author: HamidRehman
Last Updated: February 2026
Version: 1.0.0

• Express.js Documentation
• TypeScript Documentation
• Mongoose Documentation
• Winston Logger Documentation
• Express Rate Limit Documentation

For issues or questions, please open an issue in this repository.