https://github.com/somexjames/personal-finance-api
A finance management API that serves as a "sandbox" to enter possible income and expenses to view balances on future dates
https://github.com/somexjames/personal-finance-api
api api-service http http-rest-api java java-22 java-api rest rest-api spring-boot spring-framework
Last synced: about 2 months ago
JSON representation
A finance management API that serves as a "sandbox" to enter possible income and expenses to view balances on future dates
- Host: GitHub
- URL: https://github.com/somexjames/personal-finance-api
- Owner: SomexJames
- Created: 2024-08-29T02:45:28.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2024-08-29T05:38:20.000Z (8 months ago)
- Last Synced: 2025-03-02T09:17:03.498Z (about 2 months ago)
- Topics: api, api-service, http, http-rest-api, java, java-22, java-api, rest, rest-api, spring-boot, spring-framework
- Language: Java
- Homepage:
- Size: 85.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# personal-finance-api
API for personal finance management
## About the API
A Java-based API that allows you to manually input future income and expenses to visualize what your balance might look like on a given date. (i.e. "If I buy this item now, I get my pay check next week, will I have enough in my account to pay for these bills coming up after?")
## Features
This API provides HTTP endpoints and tools for the following:
* Create a user: `POST /api/v1/users`
* Add an account to a user: `POST /api/v1/users/{userId}/accounts`
* Add a transaction to an account: `POST /api/v1/accounts/{accountId}/transactions`
* Retrieve account balance for a specific date: `GET /api/v1/accounts/{accountId}/balance?date=YYYY-MM-DD`
* Get all transactions for an account: `GET /api/v1/accounts/{accountId}/transactions`
* Get the last known balance before a specific date: `GET /api/v1/accounts/{accountId}/balance/last-known?date=YYYY-MM-DD`
* Delete a transaction by ID: `DELETE /api/v1/accounts/{accountId}/transactions/{transactionId}`
## Details
### `POST /api/v1/users`
This endpoint is used to create a new user.
**Body:**
```json
{
"name": "John Doe"
}
```
**Response:**
```json
{
"id": "12345",
"name": "John Doe",
"accounts": []
}
```
**Where:**
- `id` - unique user id (automatically generated)
- `name` - the name of the user
- `accounts` - list of accounts (default empty)
### `POST /api/v1/users/{userId}/accounts`
This endpoint adds a new account to an existing user.
**Body:**
```json
{
"accountType": "CHECKING"
}
```
**Response:**
```json
{
"id": "67890",
"accountType": "CHECKING",
"dailyTransactions": {}
}
```
**Where:**
- `id` - unique account id (automatically generated)
- `accountType` - type of account: CHECKING, SAVINGS, CREDIT_CARD, CASH, etc.
- `dailyTransactions` - map containing DailyTransaction objects, keyed by date. (each DailyTransaction holds the transactions and balance information for that day)
### `POST /api/v1/accounts/{accountId}/transactions`
This endpoint adds a transaction to an account.
**Body:**
```json
{
"name": "Salary",
"amount": 1000.00,
"startDate": "2024-01-01",
"recurrencePeriod": 0,
"stopDate": null,
"maxOccurrences": 0,
"type": "INCOME"
}
```
**Response:**
```json
{
"id": "abcde",
"name": "Salary",
"amount": 1000.00,
"startDate": "2024-08-16",
"recurrencePeriod": 0,
"stopDate": null,
"maxOccurrences": 0,
"type": "INCOME"
}
```
**Where:**
- `id` - unique account id (automatically generated)
- `name` - The name or description of the transaction.
- `amount` - The transaction amount.
- `startDate` - The date the transaction starts.
- `recurrencePeriod` - The number of days between recurrences; 0 for a single occurrence.
- `stopDate` - The date to stop recurring transactions (optional).
- `maxOccurrences` - Maximum number of recurrences (optional).
- `type` - The type of transaction: INCOME or EXPENSE.
### `GET /api/v1/accounts/{accountId}/balance?date=YYYY-MM-DD`
This endpoint retrieves the account balance for a specific date.
**Response:**
```json
{
"balance": 500.00
}
```
### `GET /api/v1/accounts/{accountId}/transactions`
This endpoint returns all transactions for a given account.
**Response:**
```json
[
{
"id": "abcde",
"name": "Salary",
"amount": 1000.00,
"startDate": "2024-08-16",
"recurrencePeriod": 0,
"stopDate": null,
"maxOccurrences": 0,
"type": "INCOME"
},
{
"id": "fghij",
"name": "Rent",
"amount": 500.00,
"startDate": "2024-08-16",
"recurrencePeriod": 0,
"stopDate": null,
"maxOccurrences": 0,
"type": "EXPENSE"
}
]
```
### `GET /api/v1/accounts/{accountId}/balance/last-known?date=YYYY-MM-DD`
This endpoint returns the last known balance before the specified date.
**Response:**
```json
{
"balance": 1000.00
}
```
### `DELETE /api/v1/accounts/{accountId}/transactions/{transactionId}`
This endpoint deletes a specific transaction by ID.
**Response:**
- Status: `204` - no content
## Technologies Used
This project was developed with:
- **Java 22 (OpenJDK 22.0.2)**
- **SpringBoot 3.3.0**
- **JUnit 5** for unit testing
- **Mockito** for mocking dependencies in tests
- **Gradle** for project management and build automation
## Compile and Package
To compile and package the project into a JAR file, run:
```bash
./gradlew build
```
The JAR file will be generated in the `build/libs` directory.
## Execution
To run the API, execute the generated JAR file:
```bash
java -jar build/libs/finance-management-api.jar
```
By default, the API will be available at `http://localhost:8080/api/v1`.
## Test
To run unit tests, execute:
```bash
./gradlew test
```
This will run all unit tests and generate a report in the `build/reports/tests/test/index.html` file.