REST API (TypeScript)

This is a small REST API built with TypeScript, Express, and MongoDB. I coded it to learn how REST APIs work and to include it in my portfolio.

Why I built it

• Practice backend fundamentals: routing, controllers, middlewares, and persistence
• Learn authentication flows and cookie-based sessions
• Build a clean, readable project a recruiter can scan in a few minutes

What it does

• Registers users and logs them in
• Stores users in MongoDB via Mongoose
• Protects routes with cookie-based auth
• Allows authenticated users to list, update, and delete users

Tech stack

• TypeScript
• Node.js + Express
• MongoDB + Mongoose
• Cookie-based sessions (HTTP cookie)

How it works (architecture overview)

Request flow

1. src/index.ts boots the Express app, adds middleware, and mounts the router.
2. src/router/ declares routes and maps them to controller handlers.
3. src/controllers/ receives the request, validates input, then calls the database layer.
4. src/db/ uses Mongoose models to query MongoDB.
5. src/middlewares/ runs before protected routes to enforce auth and ownership.

Authentication flow

1. Register:
   • Accepts email, username, password.
   • Password is salted and hashed.
   • User is saved in MongoDB.
2. Login:
   • Looks up user by email and compares hashed password.
   • Generates a session token.
   • Stores the token in the user record.
   • Sends the token back as the APP-AUTH cookie.
3. Protected routes:
   • isAuthenticated reads APP-AUTH cookie.
   • The token maps to a user in MongoDB.
   • The user record is attached to req.identity.
4. Ownership checks:
   • isOwner compares req.identity._id to :id in the route.

Password hashing

• Uses HMAC with SHA-256 plus a random salt.
• A per-user salt is stored alongside the hash.

API routes

Base URL: http://localhost:8080

• POST /auth/register - Create a user
• POST /auth/login - Login and receive APP-AUTH cookie
• GET /users - List users (requires auth)
• PATCH /users/:id - Update a user (requires auth + owner)
• DELETE /users/:id - Delete a user (requires auth + owner)

Setup (step by step)

1. Install dependencies

npm install

2. Configure environment variables

cp .env.example .env

Open .env and set MONGO_URL to your MongoDB connection string. Do not commit real credentials; keep .env local.

3. Start the server

npm start

4. Try it out Register a user:

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","username":"test","password":"pass123"}'

Login to get the auth cookie:

curl -i -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"pass123"}'

Use the APP-AUTH cookie from the login response to access protected routes:

curl http://localhost:8080/users \
  -H "Cookie: APP-AUTH=<your-token>"

Project structure

• src/index.ts - Express app setup and MongoDB connection
• src/router/ - Route definitions
• src/controllers/ - Request handlers
• src/db/ - Mongoose models and queries
• src/middlewares/ - Auth and ownership checks
• src/helpers/ - Hashing utilities

Notes

• Auth is cookie-based with a session token stored in MongoDB.
• CORS is configured for http://localhost:8080.