Expense Tracker API

A RESTful API built with Node.js, Express.js, and MongoDB that allows users to manage their expenses.

Table of Contents

• Features
• Tech Stack
• Project Structure
• Installation & Setup
• API Documentation
• Authentication & Security
• Error Handling
• Contributing
• Contact

Features

• User Authentication: Register and login with JWT-based authentication.
• CRUD Operations: Create, Read, Update, and Delete expense items.
• Filtering: Fetch expense items based on categories or date ranges.
• Security: Passwords are securely hashed, and users can access only their own data.

Tech Stack

• Backend: Node.js, Express.js
• Database: MongoDB (Mongoose)
• Authentication: JWT (jsonwebtoken) & bcrypt for password hashing
• Validation: Zod
• Error Handling: Centralized middleware

Project Structure

expense-tracker-api/
│── src/
│   ├── controllers/        # Request handling logic
│   ├── models/             # Mongoose schemas
│   ├── routes/             # API route handlers
│   ├── middlewares/        # Authentication & validation
│   ├── utils/              # Utility functions
│   ├── config/             # Database & environment config
│   ├── app.ts              # Express app setup
│   ├── server.ts           # Main entry point
│── .env                    # Environment variables
│── package.json
│── README.md

Installation & Setup

1. Clone the repository

git clone https://github.com/melaku3/expense-tracker-api.git
cd expense-tracker-api

2. Install dependencies

npm install

3. Set up environment variables

Create a .env file in the root directory and configure:

PORT=3000
MONGODB_URI=your_mongodb_connection_string
JWT_SECRET=your_secret_key

4. Start the server

npm start

The API will run at http://localhost:3000.

API Documentation

User Authentication

Register a New User

POST /api/auth/signup

Request Body (JSON):

{
    "username": "johndoe",
    "email": "johndoe@example.com",
    "password": "securepassword"
}

Response:

{
    "message": "User created successfully"
}

User Login

POST /api/auth/login

Request Body (JSON):

{
    "email": "johndoe@example.com",
    "password": "securepassword"
}

Response:

{
    "message": "User logged in successfully"
}

Get Current User Profile

GET /api/auth/me

Headers:

Authorization: Bearer your_jwt_token

Response:

{
    "message": {
        "_id": "651234abcd",
        "username": "johndoe",
        "email": "johndoe@example.com",
        "role": "user"
    }
}

Expense Management

Create a New Expense

POST /api/expenses

Headers:

Authorization: Bearer your_jwt_token

Request Body (JSON):

{
    "categoryId": "651234abcd",
    "amount": 50,
    "description": "Grocery Shopping",
    "date": "2023-10-01"
}

Response:

{
    "message": "Expense created successfully"
}

Get All Expenses

GET /api/expenses

Headers:

Authorization: Bearer your_jwt_token

Response:

[
    {
        "_id": "651234abcd",
        "categoryId": {
            "_id": "651234abcd",
            "type": "expense",
            "name": "Grocery",
            "colorCode": "#ff0000",
            "description": "Grocery Shopping"
        },
        "amount": 50,
        "description": "Grocery Shopping",
        "date": "2023-10-01",
        "userId": {
            "_id": "651234abcd",
            "username": "johndoe",
            "email": "johndoe@example.com",
            "role": "user"
        }
    }
]

Get a Single Expense

GET /api/expenses/:id

Headers:

Authorization: Bearer your_jwt_token

Response:

{
    "_id": "651234abcd",
    "categoryId": {
        "_id": "651234abcd",
        "type": "expense",
        "name": "Grocery",
        "colorCode": "#ff0000",
        "description": "Grocery Shopping"
    },
    "amount": 50,
    "description": "Grocery Shopping",
    "date": "2023-10-01",
    "userId": {
        "_id": "651234abcd",
        "username": "johndoe",
        "email": "johndoe@example.com",
        "role": "user"
    }
}

Update an Expense

PATCH /api/expenses/:id

Headers:

Authorization: Bearer your_jwt_token

Request Body (JSON):

{
    "amount": 60
}

Response:

{
    "message": "Expense updated successfully"
}

Delete an Expense

DELETE /api/expenses/:id

Headers:

Authorization: Bearer your_jwt_token

Response:

{
    "message": "Expense deleted successfully"
}

Filter Expenses

GET /api/expenses/filter

Headers:

Authorization: Bearer your_jwt_token

Query Parameters:

categoryId, minAmount, maxAmount, startDate, endDate, sortBy, limit, page

Response:

[
    {
        "_id": "651234abcd",
        "categoryId": {
            "_id": "651234abcd",
            "type": "expense",
            "name": "Grocery",
            "colorCode": "#ff0000",
            "description": "Grocery Shopping"
        },
        "amount": 50,
        "description": "Grocery Shopping",
        "date": "2023-10-01",
        "userId": {
            "_id": "651234abcd",
            "username": "johndoe",
            "email": "johndoe@example.com",
            "role": "user"
        }
    }
]

Category Management

Create a New Category

POST /api/categories

Headers:

Authorization: Bearer your_jwt_token

Request Body (JSON):

{
    "name": "Grocery",
    "type": "expense",
    "description": "Grocery Shopping",
    "colorCode": "#ff0000"
}

Response:

{
    "message": "Category created successfully"
}

Get All Categories

GET /api/categories

Headers:

Authorization: Bearer your_jwt_token

Response:

[
    {
        "_id": "651234abcd",
        "name": "Grocery",
        "type": "expense",
        "description": "Grocery Shopping",
        "colorCode": "#ff0000",
        "userId": {
            "_id": "651234abcd",
            "username": "johndoe",
            "email": "johndoe@example.com",
            "role": "user"
        }
    }
]

Get a Single Category

GET /api/categories/:id

Headers:

Authorization: Bearer your_jwt_token

Response:

{
    "_id": "651234abcd",
    "name": "Grocery",
    "type": "expense",
    "description": "Grocery Shopping",
    "colorCode": "#ff0000",
    "userId": {
        "_id": "651234abcd",
        "username": "johndoe",
        "email": "johndoe@example.com",
        "role": "user"
    }
}

Update a Category

PATCH /api/categories/:id

Headers:

Authorization: Bearer your_jwt_token

Request Body (JSON):

{
    "name": "Supermarket"
}

Response:

{
    "message": "Category updated successfully"
}

Delete a Category

DELETE /api/categories/:id

Headers:

Authorization: Bearer your_jwt_token

Response:

{
    "message": "Category deleted successfully"
}

Authentication & Security

• JWT Authentication: Users must include a valid JWT token in the Authorization header to access protected routes.
• Password Hashing: Uses bcrypt to securely hash passwords.
• Access Control: Users can only manage their own expenses.

Error Handling

Error Type	Response Code	Example Message
Invalid Credentials	401	"Invalid email or password"
Unauthorized Access	403	"Access denied"
Resource Not Found	404	"Expense not found"
Validation Error	400	"Field is required"
Server Error	500	"Internal server error"

Contributing

Contributions are welcome! Please fork the repository and create a pull request.

Contact

For any issues, feel free to reach out! 🚀
Email: emelaku63@gmail.com
GitHub: melaku3