{"id":23391591,"url":"https://github.com/xdaybreakerx/finance-management-api","last_synced_at":"2026-05-03T23:32:16.589Z","repository":{"id":226705621,"uuid":"765953781","full_name":"xdaybreakerx/finance-management-api","owner":"xdaybreakerx","description":"A Flask based Finance Management API designed to empower individuals, and small businesses to manage their data. ","archived":false,"fork":false,"pushed_at":"2024-03-24T08:25:32.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-08T14:51:01.951Z","etag":null,"topics":["flask","postgresql","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xdaybreakerx.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-03-02T00:23:58.000Z","updated_at":"2024-10-02T11:48:29.000Z","dependencies_parsed_at":"2024-12-22T04:18:54.093Z","dependency_job_id":"b6ab9cf0-699a-4646-9cff-640392dd6c14","html_url":"https://github.com/xdaybreakerx/finance-management-api","commit_stats":null,"previous_names":["xdaybreakerx/xandersalathe_t2a2","xdaybreakerx/finance-management-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xdaybreakerx/finance-management-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdaybreakerx%2Ffinance-management-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdaybreakerx%2Ffinance-management-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdaybreakerx%2Ffinance-management-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdaybreakerx%2Ffinance-management-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xdaybreakerx","download_url":"https://codeload.github.com/xdaybreakerx/finance-management-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdaybreakerx%2Ffinance-management-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272466763,"owners_count":24939462,"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","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["flask","postgresql","python3"],"created_at":"2024-12-22T04:18:42.014Z","updated_at":"2026-05-03T23:32:11.557Z","avatar_url":"https://github.com/xdaybreakerx.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xander Salathe - Coder Academy - T2A2 - API Webserver Project\n\n## Introduction\n\nThe Finance Manager API is a backend service designed to empower individuals and small businesses to effectively manage their financial data. It provides a comprehensive suite of features for tracking transactions, managing accounts, and categorizing expenses and income. By offering endpoints for creating, reading, updating, and deleting financial records, it adheres to the RESTful principles, ensuring a scalable, flexible, and intuitive interface for developers and applications.\n\n## System/Hardware Requirements\n\n- No specific hardware requirements.\n- Operating System: Compatible with any OS that can run Python 3 (e.g., Windows, macOS, Linux).\n\n## App Setup\n\nAll endpoints are documented in this README document, and can be imported from the endpoints.json file to either Insomnia, or Postman.\n\nTo run from local machine using postgreSQL:\n\n1. Create a new postgreSQL User and give Permissions\n2. Create a postgreSQL Database\n3. Edit \".env\" file so \"SQL_DATABASE_URI\" matches user and database details\n4. Start python virtual invironment (python3 -m venv venv)\n5. Activate virtual environment (source venv/bin/activate)\n6. Install requirements (pip3 install -r requirements.txt)\n7. Create and seed tables (flask db drop \u0026\u0026 flask db create \u0026\u0026 flask db seed)\n8. Run flask app (flask run)\n\n## Note for assessors:\n\nFor ease of assessment, I have created a postgreSQL Databased hosted via [Neon.tech](neon.tech) - as such no configuration is required on your end to test functionality of this application.\n\nThe details for this are saved in the .env file included in submission, however for obvious reasons this is not shared directly to GitHub. As such, the only steps needed to be taken is to create and seed the tables, and run the flask server:\n\n1. `flask db drop \u0026\u0026 flask db create \u0026\u0026 flask db seed`\n\n2. `flask run`\n\n## License\n\nDistributed under the terms of the MIT License\n\n\n## API Endpoint Documentation\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick here for response \u003c/summary\u003e\n\n## Account Controller:\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick here for Account Controller Endpoints \u003c/summary\u003e\n\n### 1. Create a New Account\n\n### `/accounts - POST`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nUsed to create a new Account in relation to a User\n\n#### Required parameters:\n\n- `account_type`: (`str`) type or description of account\n- `balance`: (`int`) initial value of account\n\neg\n\n```json\n{\n  \"account_type\": \"savings\",\n  \"balance\": 15000\n}\n```\n\n#### Expected response:\n\nJSON response of Account, 201\n\nExample response:\n\n```json\n{\n  \"id\": 4,\n  \"account_type\": \"test\",\n  \"balance\": \"15000.00\",\n  \"transactions\": [],\n  \"date_created\": \"2024-03-22T09:55:02.430673\",\n  \"user\": {\n    \"username\": \"User\",\n    \"email\": \"user@email.com\"\n  }\n}\n```\n\n### 2. Get a List of All Accounts (with Role-Based Filtering)\n\n### `/accounts - GET`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nRetrieves a list of all accounts. Auditors can see all accounts, while other users see only their own.\n\n#### No parameters required.\n\n#### Expected response:\n\nJSON array of Account objects.\n\nExample response:\n\n```json\n[\n  {\n    \"id\": 1,\n    \"account_type\": \"savings\",\n    \"balance\": \"1234.56\",\n    \"date_created\": \"2024-03-20T12:34:56.789Z\",\n    \"user\": {\n      \"username\": \"Admin\",\n      \"email\": \"admin@email.com\"\n    }\n  }\n]\n```\n\n\n### 3. Get a Specific Account\n\n### `/accounts/\u003caccount_id\u003e - GET`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nRetrieves information about a specific account. Auditors can view any account, while other users can only view their own accounts.\n\n#### Required parameters:\n\n- `account_id`: URL parameter specifying the account's ID.\n\n#### Expected response:\n\nJSON representation of the specified Account\n\nExample response:\n\n```json\n{\n  \"id\": 2,\n  \"account_type\": \"checking\",\n  \"balance\": \"5000.00\",\n  \"date_created\": \"2024-03-21T11:22:33.444Z\",\n  \"user\": {\n    \"username\": \"User\",\n    \"email\": \"user@email.com\"\n  }\n}\n```\n\n### 4. Update an Existing Account\n\n### `/accounts/\u003caccount_id\u003e - PUT/PATCH`\n\n**This endpoint is protected and requires a valid JWT token. Only Admins can update accounts not owned by themselves.**\n\n#### Description:\n\nUpdates information about a specific account.\n\n#### Required parameters:\n\n- `account_type`: (Optional, `str`) New type or description of the account.\n- `balance`: (Optional, `int`) New balance value for the account.\n\n#### Example request:\n\n```json\n{\n  \"account_type\": \"emergency fund\",\n  \"balance\": 20000\n}\n```\n\n#### Expected response:\n\nJSON representation of the updated Account, 201.\n\n#### Example response:\n\n```json\n{\n  \"id\": 2,\n  \"account_type\": \"emergency fund\",\n  \"balance\": \"20000.00\",\n  \"transactions\": [],\n  \"date_created\": \"2024-03-21T11:22:33.444Z\",\n  \"user\": {\n    \"username\": \"User\",\n    \"email\": \"user@email.com\"\n  }\n}\n```\n\n### 5. Delete an Existing Account\n\n### `/accounts/\u003caccount_id\u003e - DELETE`\n\n**This endpoint is protected and requires a valid JWT token. Only Admins can delete accounts not owned by themselves.**\n\n#### Description:\n\nDeletes a specific account.\n\n#### Required parameters:\n\n- `account_id`: URL parameter specifying the account's ID.\n\n#### Expected response:\n\nConfirmation message of the deleted account, 201\n\nExample response:\n\n```json\n{\n  \"message\": \"Account 'emergency fund' deleted successfully\"\n}\n```\n\n### 6. Get Total Balance (Auditor Only)\n\n### `/accounts/total_balance - GET`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Auditor\" role.**\n\n#### Description:\n\nCalculates the total balance across all accounts in the system.\n\n#### No parameters required.\n\n#### Expected response:\n\nJSON object with the total balance.\n\nExample response:\n\n```json\n{\n  \"total_balance\": \"27345.01\"\n}\n```\n\n\n### 7. Rank Transactions within an Account (Auditor Only)\n\n### `/accounts/\u003cint:account_id\u003e/transactions/rank - GET`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Auditor\" role.**\n\n#### Description:\n\nRanks transactions within a specific account based on the amount, showing the relative size of each transaction.\n\n#### Required parameters:\n\n- `account_id`: URL parameter specifying the account's ID to rank transactions within.\n\n#### Expected response:\n\nJSON array of transactions with their ranks.\n\nExample response:\n\n```json\n[\n  {\n    \"transaction_id\": 3,\n    \"amount\": \"-500.00\",\n    \"rank\": 1\n  },\n  {\n    \"transaction_id\": 1,\n    \"amount\": \"-300.00\",\n    \"rank\": 2\n  }\n]\n```\n\n### 8. Account Summary (Auditor Only)\n\n### `/accounts/summary - GET`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Auditor\" role.**\n\n#### Description:\n\nProvides a summary of each account including the account ID, type, and total spent in transactions.\n\n#### No parameters required.\n\n#### Expected response:\n\nJSON array with a summary for each account.\n\nExample response:\n\n```json\n[\n  {\n    \"account_id\": 1,\n    \"account_type\": \"savings\",\n    \"total_spent\": \"-560.00\"\n  },\n  {\n    \"account_id\": 2,\n    \"account_type\": \"checking\",\n    \"total_spent\": \"-1230.00\"\n  }\n]\n```\n\n### 9. Search Transactions (with Role-Based Filtering)\n\n### `/accounts/search - POST`\n\n**This endpoint is protected and requires a valid JWT token. It enables searching for transactions based on a description, with results filtered by the user's role.**\n\n#### Description:\n\nAllows users to search for transactions across all accounts if they have the \"Auditor\" role. Regular users can only search within their own accounts.\n\n#### Required parameters (in JSON body):\n\n- `query`: (`str`) The search term to filter transactions by their description.\n\nExample request:\n\n```json\n{\n  \"query\": \"groceries\"\n}\n```\n\n#### Expected response:\n\nJSON array of transactions matching the search term, filtered according to the user's role.\n\nExample response (for an \"Auditor\"):\n\n```json\n[\n  {\n    \"id\": 2,\n    \"amount\": \"-123.45\",\n    \"description\": \"groceries at mart\",\n    \"transaction_date\": \"2024-03-22T09:55:02.430673\",\n    \"account\": {\n      \"id\": 1,\n      \"account_type\": \"checking\"\n    }\n  }\n]\n```\n\n\u003c/details\u003e\n\n## Auth Controller:\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick here for Auth Controller Endpoints \u003c/summary\u003e\n\n### 1. Get All Users (Auditor Only)\n\n### `/auth/users - GET`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Auditor\" role.**\n\n#### Description:\n\nRetrieves a list of all registered users in the system.\n\n#### No parameters required.\n\n#### Expected response:\n\nJSON array of User objects, 201\n\nExample response:\n\n```sql\n[\n    {\n        \"id\": 1,\n        \"username\": \"Admin\",\n        \"email\": \"admin@email.com\",\n        \"role\": \"Admin\",\n        \"date_created\": \"2024-03-20T12:00:00Z\"\n    }\n]\n```\n\n### 2. Register a New User\n\n### `/auth/register - POST`\n\n**This endpoint is open and does not require a JWT token.**\n\n#### Description:\n\nAllows new users to register by providing a username, email, and password.\n\n#### Required parameters:\n\n- `username`: (`str`) The user's chosen username.\n- `email`: (`str`) The user's email address.\n- `password`: (`str`) The user's chosen password.\n\nExample request:\n\n```json\n{\n  \"username\": \"newuser\",\n  \"email\": \"newuser@email.com\",\n  \"password\": \"password123\"\n}\n```\n\n#### Expected response:\n\nJSON response of the created User object, 201.\n\nExample response:\n\n```json\n{\n  \"id\": 3,\n  \"username\": \"newuser\",\n  \"email\": \"newuser@email.com\",\n  \"role\": \"User\",\n  \"date_created\": \"2024-03-22T10:00:00Z\"\n}\n```\n\n### 3. User Login\n\n### `/auth/login - POST`\n\n**This endpoint is open and does not require a JWT token.**\n\n#### Description:\n\nAuthenticates a user by their email and password, returning a JWT token if successful.\n\n#### Required parameters:\n\n- `email`: (`str`) The user's email address.\n- `password`: (`str`) The user's password.\n\nExample request:\n\n```json\n{\n  \"email\": \"user@email.com\",\n  \"password\": \"password123\"\n}\n```\n\n#### Expected response:\n\nJSON object containing the user's email, JWT token, and role, 201\n\nExample Response:\n\n```json\n{\n  \"email\": \"user@email.com\",\n  \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"role\": \"User\"\n}\n```\n\n### 4. Delete a User (Admin only)\n\n### `/auth/\u003cint:user_id\u003e - DELETE`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Admin\" role.**\n\n#### Description:\n\nDeletes a specific user from the system.\n\n#### Required parameters:\n\n- `user_id`: URL parameter specifying the user's ID to be deleted.\n\n#### Expected response:\n\nConfirmation message of the deleted user, 201\n\nExample response:\n\n```json\n{\n  \"message\": \"User 'newuser', 'User' deleted successfully\"\n}\n```\n\n\u003c/details\u003e\n\n## Category Controller:\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick here for Category Controller Endpoints \u003c/summary\u003e\n\n### 1. Add a New Category for Future Transactions\n\n### `/categories - POST`\n\n**This endpoint is protected and requires a valid JWT token. Only users except those with the \"Auditor\" role can add categories.**\n\n#### Description:\n\nAllows creating a new category that can be assigned to future transactions.\n\n#### Required parameters:\n\n- `name`: (`str`) The name of the category.\n- `description`: (`str`, optional) A description of the category.\n\nExample request:\n\n```json\n{\n  \"name\": \"Utilities\",\n  \"description\": \"Monthly bills for utilities\"\n}\n```\n\n#### Expected response:\n\nJSON response of the created Category object, 201.\n\nExample response:\n\n```json\n{\n  \"id\": 1,\n  \"name\": \"Utilities\",\n  \"description\": \"Monthly bills for utilities\"\n}\n```\n\n### 2. Get All Categories\n\n### `/categories - GET`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nRetrieves a list of all categories available in the system.\n\n#### No parameters required.\n\n#### Expected response:\n\nJSON array of Category objects, 201\n\nExample response:\n\n```json\n[\n  {\n    \"id\": 1,\n    \"name\": \"Utilities\",\n    \"description\": \"Monthly bills for utilities\"\n  }\n]\n```\n\n\n### 3. Get a Specific Category\n\n### `/categories/\u003ccategory_id\u003e - GET`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nRetrieves information about a specific category by its ID.\n\n#### Required parameters:\n\n- `category_id`: URL parameter specifying the category's ID.\n\n#### Expected response:\n\nJSON representation of the specified Category, 201\n\nExample response:\n\n```json\n{\n  \"id\": 1,\n  \"name\": \"Utilities\",\n  \"description\": \"Monthly bills for utilities\"\n}\n```\n\n### 4. Update an Existing Category for Transactions\n\n### `/categories/\u003ccategory_id\u003e - PUT/PATCH`\n\n**This endpoint is protected and requires a valid JWT token. Only an Admin can update a category once created.**\n\n#### Description:\n\nUpdates information about a specific category.\n\n#### Required parameters:\n\n- `name`: (`str`, optional) New name of the category.\n- `description`: (`str`, optional) New description of the category.\n\n#### Example request:\n\n```json\n{\n  \"name\": \"Monthly Utilities\",\n  \"description\": \"Updated description for utilities\"\n}\n```\n\n#### Expected response:\n\nJSON representation of the updated Category, 200.\n\nExample response:\n\n```json\n{\n  \"id\": 1,\n  \"name\": \"Monthly Utilities\",\n  \"description\": \"Updated description for utilities\"\n}\n```\n\n### 5. Delete a category\n\n### `/categories/\u003ccategory_id\u003e - DELETE`\n\n**This endpoint is protected and requires a valid JWT token. Only an Admin can delete a category.**\n\n#### Description:\n\nDeletes a specific category from the system.\n\n#### Required parameters:\n\n- `category_id`: URL parameter specifying the category's ID to be deleted.\n\n#### Expected response:\n\nConfirmation message of the deleted category.\n\nExample response:\n\n```json\n{\n  \"message\": \"Category with id 1, Name: Utilities, and Description: Monthly bills for utilities deleted successfully\"\n}\n```\n\n\u003c/details\u003e\n\n## Transaction Controller:\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick here for Transaction Controller Endpoints \u003c/summary\u003e\n\n### 1. Add a New Transaction\n\n### `/accounts/\u003cint:account_id\u003e/transactions - POST`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nAllows adding a new transaction to a specific account. Users can add transactions only to their own accounts, except for admins who can add transactions to any account.\n\n#### Required parameters for the account identified by \u003cint:account_id\u003e:\n\n- `amount`: (`int`) The transaction amount. A positive value for deposits, negative for withdrawals.\n- `description`: (`str`, optional) A description of the transaction.\n\nExample request:\n\n```json\n{\n  \"amount\": -50.75,\n  \"description\": \"Grocery shopping\"\n}\n```\n\n#### Expected response:\n\nJSON response of the created Transaction object, 201.\n\nExample response:\n\n```json\n{\n  \"id\": 1,\n  \"amount\": \"-50.75\",\n  \"description\": \"Grocery shopping\",\n  \"transaction_date\": \"2024-03-23T12:00:00Z\",\n  \"account_id\": 1\n}\n```\n\n### 2. Update an Existing Transaction (Admin Only)\n\n### `/accounts/\u003cint:account_id\u003e/transactions/\u003cint:transaction_id\u003e - PUT/PATCH`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Admin\" role.**\n\n#### Description:\n\nUpdates information about a specific transaction within a specific account.\n\n#### Required parameters:\n\n- `amount`: (`int`, optional) New amount of the transaction.\n- `description`: (`str`, optional) New description of the transaction.\n\nExample request:\n\n```json\n{\n  \"amount\": -45.0,\n  \"description\": \"Supermarket shopping\"\n}\n```\n\n#### Expected response:\n\nJSON representation of the updated Transaction, 200.\n\nExample response:\n\n```json\n{\n  \"id\": 1,\n  \"amount\": \"-45.00\",\n  \"description\": \"Supermarket shopping\",\n  \"transaction_date\": \"2024-03-23T12:00:00Z\",\n  \"account_id\": 1\n}\n```\n\n### 3. Delete a Transaction (Admin Only)\n\n### `/accounts/\u003cint:account_id\u003e/transactions/\u003cint:transaction_id\u003e - DELETE`\n\n**This endpoint is protected and requires a valid JWT token. Only accessible by users with the \"Admin\" role.**\n\n#### Description:\n\nDeletes a specific transaction from a specific account.\n\n#### No parameters required beyond the URL parameters.\n\n#### Expected response:\n\nConfirmation message of the deleted transaction.\n\nExample response:\n\n```json\n{\n  \"message\": \"Transaction with id 1, Description: 'Supermarket shopping', Amount: -45.00 deleted successfully\"\n}\n```\n\n### 4. Search Transactions (Role-Based Filtering)\n\n### `/accounts/search - POST`\n\n**This endpoint is protected and requires a valid JWT token.**\n\n#### Description:\n\nSearches transactions based on a description query. Auditors can see all transactions across all accounts, while other users can only see transactions within their own accounts.\n\n### Required parameters:\n\n- `query`: (`str`) The search term to match against transaction descriptions.\n  Example request:\n\n```json\n{\n  \"query\": \"shopping\"\n}\n```\n\n#### Expected response:\n\nJSON array of Transaction objects that match the search term.\n\nExample response:\n\n```json\n[\n  {\n    \"id\": 1,\n    \"account_id\": 1,\n    \"amount\": \"-45.00\",\n    \"description\": \"Supermarket shopping\",\n    \"transaction_date\": \"2024-03-23T12:00:00Z\"\n  }\n]\n```\n\n\u003c/details\u003e\n\n\u003c/details\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdaybreakerx%2Ffinance-management-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdaybreakerx%2Ffinance-management-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdaybreakerx%2Ffinance-management-api/lists"}