{"id":15196781,"url":"https://github.com/somexjames/personal-finance-api","last_synced_at":"2026-03-07T04:33:24.065Z","repository":{"id":255303710,"uuid":"849122689","full_name":"SomexJames/personal-finance-api","owner":"SomexJames","description":"A finance management API that serves as a \"sandbox\" to enter possible income and expenses to view balances on future dates","archived":false,"fork":false,"pushed_at":"2024-08-29T05:38:20.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-02T09:17:03.498Z","etag":null,"topics":["api","api-service","http","http-rest-api","java","java-22","java-api","rest","rest-api","spring-boot","spring-framework"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SomexJames.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-29T02:45:28.000Z","updated_at":"2024-08-29T05:47:18.000Z","dependencies_parsed_at":"2024-08-29T06:39:53.746Z","dependency_job_id":"7d004ae2-6c4e-4da2-983e-afda9b6c072d","html_url":"https://github.com/SomexJames/personal-finance-api","commit_stats":null,"previous_names":["somexjames/personal-finance-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SomexJames%2Fpersonal-finance-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SomexJames%2Fpersonal-finance-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SomexJames%2Fpersonal-finance-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SomexJames%2Fpersonal-finance-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SomexJames","download_url":"https://codeload.github.com/SomexJames/personal-finance-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241482101,"owners_count":19969850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-service","http","http-rest-api","java","java-22","java-api","rest","rest-api","spring-boot","spring-framework"],"created_at":"2024-09-28T00:03:20.366Z","updated_at":"2026-03-07T04:33:24.004Z","avatar_url":"https://github.com/SomexJames.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# personal-finance-api\n\nAPI for personal finance management\n\n## About the API\n\nA 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?\")\n\n## Features\n\nThis API provides HTTP endpoints and tools for the following:\n\n* Create a user: `POST /api/v1/users`\n* Add an account to a user: `POST /api/v1/users/{userId}/accounts`\n* Add a transaction to an account: `POST /api/v1/accounts/{accountId}/transactions`\n* Retrieve account balance for a specific date: `GET /api/v1/accounts/{accountId}/balance?date=YYYY-MM-DD`\n* Get all transactions for an account: `GET /api/v1/accounts/{accountId}/transactions`\n* Get the last known balance before a specific date: `GET /api/v1/accounts/{accountId}/balance/last-known?date=YYYY-MM-DD`\n* Delete a transaction by ID: `DELETE /api/v1/accounts/{accountId}/transactions/{transactionId}`\n\n## Details\n\n### `POST /api/v1/users`\n\nThis endpoint is used to create a new user.\n\n**Body:**\n\n```json\n{\n  \"name\": \"John Doe\"\n}\n```\n\n**Response:**\n\n```json\n{\n  \"id\": \"12345\",\n  \"name\": \"John Doe\",\n  \"accounts\": []\n}\n```\n\n**Where:**\n\n- `id` - unique user id (automatically generated)\n- `name` - the name of the user\n- `accounts` - list of accounts (default empty)\n\n### `POST /api/v1/users/{userId}/accounts`\n\nThis endpoint adds a new account to an existing user.\n\n**Body:**\n\n```json\n{\n  \"accountType\": \"CHECKING\"\n}\n```\n\n**Response:**\n\n```json\n{\n  \"id\": \"67890\",\n  \"accountType\": \"CHECKING\",\n  \"dailyTransactions\": {}\n}\n```\n\n**Where:**\n\n- `id` - unique account id (automatically generated)\n- `accountType` - type of account: CHECKING, SAVINGS, CREDIT_CARD, CASH, etc.\n- `dailyTransactions` - map containing DailyTransaction objects, keyed by date. (each DailyTransaction holds the transactions and balance information for that day)\n\n### `POST /api/v1/accounts/{accountId}/transactions`\n\nThis endpoint adds a transaction to an account.\n\n**Body:**\n\n```json\n{\n  \"name\": \"Salary\",\n  \"amount\": 1000.00,\n  \"startDate\": \"2024-01-01\",\n  \"recurrencePeriod\": 0,\n  \"stopDate\": null,\n  \"maxOccurrences\": 0,\n  \"type\": \"INCOME\"\n}\n```\n\n**Response:**\n\n```json\n{\n  \"id\": \"abcde\",\n  \"name\": \"Salary\",\n  \"amount\": 1000.00,\n  \"startDate\": \"2024-08-16\",\n  \"recurrencePeriod\": 0,\n  \"stopDate\": null,\n  \"maxOccurrences\": 0,\n  \"type\": \"INCOME\"\n}\n```\n\n**Where:**\n\n- `id` - unique account id (automatically generated)\n- `name` - The name or description of the transaction.\n- `amount` - The transaction amount.\n- `startDate` - The date the transaction starts.\n- `recurrencePeriod` - The number of days between recurrences; 0 for a single occurrence.\n- `stopDate` - The date to stop recurring transactions (optional).\n- `maxOccurrences` - Maximum number of recurrences (optional).\n- `type` - The type of transaction: INCOME or EXPENSE.\n\n### `GET /api/v1/accounts/{accountId}/balance?date=YYYY-MM-DD`\n\nThis endpoint retrieves the account balance for a specific date.\n\n**Response:**\n\n```json\n{\n  \"balance\": 500.00\n}\n```\n\n### `GET /api/v1/accounts/{accountId}/transactions`\n\nThis endpoint returns all transactions for a given account.\n\n**Response:**\n\n```json\n[\n  {\n    \"id\": \"abcde\",\n    \"name\": \"Salary\",\n    \"amount\": 1000.00,\n    \"startDate\": \"2024-08-16\",\n    \"recurrencePeriod\": 0,\n    \"stopDate\": null,\n    \"maxOccurrences\": 0,\n    \"type\": \"INCOME\"\n  },\n  {\n    \"id\": \"fghij\",\n    \"name\": \"Rent\",\n    \"amount\": 500.00,\n    \"startDate\": \"2024-08-16\",\n    \"recurrencePeriod\": 0,\n    \"stopDate\": null,\n    \"maxOccurrences\": 0,\n    \"type\": \"EXPENSE\"\n  }\n]\n```\n\n### `GET /api/v1/accounts/{accountId}/balance/last-known?date=YYYY-MM-DD`\n\nThis endpoint returns the last known balance before the specified date.\n\n**Response:**\n\n```json\n{\n  \"balance\": 1000.00\n}\n```\n\n### `DELETE /api/v1/accounts/{accountId}/transactions/{transactionId}`\n\nThis endpoint deletes a specific transaction by ID.\n\n**Response:**\n\n- Status: `204` - no content\n\n## Technologies Used\n\nThis project was developed with:\n\n- **Java 22 (OpenJDK 22.0.2)**\n- **SpringBoot 3.3.0**\n- **JUnit 5** for unit testing\n- **Mockito** for mocking dependencies in tests\n- **Gradle** for project management and build automation\n\n## Compile and Package\n\nTo compile and package the project into a JAR file, run:\n\n```bash\n./gradlew build\n```\n\nThe JAR file will be generated in the `build/libs` directory.\n\n## Execution\n\nTo run the API, execute the generated JAR file:\n\n```bash\njava -jar build/libs/finance-management-api.jar\n```\n\nBy default, the API will be available at `http://localhost:8080/api/v1`.\n\n## Test\n\nTo run unit tests, execute:\n\n```bash\n./gradlew test\n```\n\nThis will run all unit tests and generate a report in the `build/reports/tests/test/index.html` file.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsomexjames%2Fpersonal-finance-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsomexjames%2Fpersonal-finance-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsomexjames%2Fpersonal-finance-api/lists"}