{"id":29691972,"url":"https://github.com/acskii/expense-tracker-api","last_synced_at":"2026-05-07T00:40:08.457Z","repository":{"id":305927518,"uuid":"1023460968","full_name":"acskii/expense-tracker-api","owner":"acskii","description":"A self-host local network expense API that tracks all transactions","archived":false,"fork":false,"pushed_at":"2025-07-22T17:01:33.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-22T19:04:20.342Z","etag":null,"topics":["api","expense-tracker","java","spring","spring-boot"],"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/acskii.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,"zenodo":null}},"created_at":"2025-07-21T07:43:07.000Z","updated_at":"2025-07-22T17:01:36.000Z","dependencies_parsed_at":"2025-07-22T19:04:23.131Z","dependency_job_id":"e44527c2-061a-4aba-9d4e-7ba58bfbbf50","html_url":"https://github.com/acskii/expense-tracker-api","commit_stats":null,"previous_names":["acskii/expense-tracker-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/acskii/expense-tracker-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acskii%2Fexpense-tracker-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acskii%2Fexpense-tracker-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acskii%2Fexpense-tracker-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acskii%2Fexpense-tracker-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acskii","download_url":"https://codeload.github.com/acskii/expense-tracker-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acskii%2Fexpense-tracker-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266633916,"owners_count":23959653,"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-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":["api","expense-tracker","java","spring","spring-boot"],"created_at":"2025-07-23T07:08:47.679Z","updated_at":"2026-05-07T00:40:08.451Z","avatar_url":"https://github.com/acskii.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Expense Tracker API\n\n## Endpoints\n\n---\n\nTo interact with any other endpoint, you need an Authorization token.\n\nTo get an Authorization token, you must log in to a registered user account.\n\n### 1] Registration:\n\n----\n**Endpoint**: `POST` `api/auth/register`\n\n**Request Body**: \n```json\n{\n  \"name\": \"USER NAME\",\n  \"email\": \"VALID EMAIL ADDRESS\",\n  \"password\": \"PASSWORD\"\n}\n```\n\n--\n\n**Response**:\n\n**[STATUS CODE: 200]**\n```json\n{\n  \"name\": \"USER NAME\",\n  \"email\": \"EMAIL ADDRESS\"\n}\n```\n----\n\n### 2] Login:\n\n----\n**Endpoint**: `POST` `api/auth/login`\n\n**Request Body**:\n```json\n{\n  \"email\": \"REGISTERED EMAIL ADDRESS\",\n  \"password\": \"PASSWORD\"\n}\n```\n\n--\n\n**Response**:\n\n**[STATUS CODE: 200]**\n\n```json\n{\n  \"token\": \"AUTHORIZATION TOKEN\"\n}\n```\n----\n\n### 3] Check token validity:\n\n----\n**Endpoint**: `GET` `api/auth/health`\n\n**Headers**:\n```json\n{\n  \"Authorization\": \"Bearer \u003cTOKEN\u003e\"\n}\n```\n**NO Request Body**\n\n--\n\n**Response if valid**:\n\n**[STATUS CODE: 200]**\n\n```json\n{\n  \"name\": \"USER NAME\",\n  \"email\": \"EMAIL ADDRESS\",\n  \"balance\": 123.45\n}\n```\n\n--\n\n**Response if _not_ valid**:\n\n**[STATUS CODE: 401]**\n\n**NO Response Body**\n\n----\n\n### 4] Users:\n\n----\n**Endpoint**: `GET` `api/user`\n\n**Headers**:\n```json\n{\n  \"Authorization\": \"Bearer \u003cTOKEN\u003e\"\n}\n```\n**NO Request Body**\n\n--\n\n**Response if valid**:\n\n**[STATUS CODE: 200]**\n\n```json\n{\n  \"name\": \"USER NAME\",\n  \"email\": \"EMAIL ADDRESS\",\n  \"balance\": 123.45\n}\n```\n\n--\n\n**Response if _not_ valid**:\n\n**[STATUS CODE: 401]**\n\n**NO Response Body**\n\n----\n\n### 5] Transactions:\n\n\u003e [!IMPORTANT] \n\u003e \n\u003e For **ALL** requests mentioned below, an Authorization token must be provided for a request to process.\n\u003e \n\u003e Include this header in any request:\n\u003e \n\u003e **Headers**:\n\u003e ```json\n\u003e {\n\u003e     \"Authorization\": \"Bearer \u003cTOKEN\u003e\"\n\u003e }\n\u003e ```\n\u003e \n\u003e Otherwise an `Unauthorized` response will be given (of status code **401**)\n\n----\n**Endpoint**: `GET` `api/transactions`\n\n\n**NO Request Body**\n\n--\n\n**Response if valid**:\n\n**[STATUS CODE: 200]**\n\n**Response Body**:\n```json\n[\n  {\n    \"id\": \"UUID\",\n    \"name\": \"TRANSACTION NAME\",\n    \"description\": \"DESCRIPTION\",\n    \"amount\": 999.99,\n    \"type\": \"INCOME/EXPENSE\",\n    \"profit\": true, \n    \"location\": \"LOCATION\", \n    \"method\": \"CARD/CASH\"\n  }\n]\n```\n\n----\n\n----\n**Endpoint**: `POST` `api/transactions`\n\n**Request Body**:\n```json\n{\n   \"id\": \"UUID\",\n   \"name\": \"TRANSACTION NAME\",\n   \"description\": \"DESCRIPTION\",\n   \"amount\": 999.99,\n   \"type\": \"INCOME/EXPENSE\",\n   \"location\": \"LOCATION\",\n   \"method\": \"CARD/CASH\"\n}\n```\n\n--\n\n**Response if valid**:\n\n**[STATUS CODE: 201]**\n\n----\n\n----\n**Endpoint**: `GET` `api/transactions/{id}`\n\n\n**NO Request Body**\n\n--\n\n**Response if valid**:\n\n**[STATUS CODE: 200]**\n\n**Response Body**:\n```json\n{\n   \"id\": \"UUID\",\n   \"name\": \"TRANSACTION NAME\",\n   \"description\": \"DESCRIPTION\",\n   \"amount\": 999.99,\n   \"type\": \"INCOME/EXPENSE\",\n   \"profit\": true,\n   \"location\": \"LOCATION\",\n   \"method\": \"CARD/CASH\"\n}\n```\n\n----\n\n----\n**Endpoint**: `PATCH` `api/transactions/{id}`\n\n**Request Body**:\n\u003e `name?` means that you may or may not include it\n\n```json\n{\n   \"name?\": \"TRANSACTION NAME\",\n   \"description?\": \"DESCRIPTION\",\n   \"amount?\": 999.99,\n   \"type?\": \"INCOME/EXPENSE\",\n   \"location?\": \"LOCATION\",\n   \"method?\": \"CARD/CASH\"\n}\n```\n\n--\n\n**Response if valid**:\n\n**[STATUS CODE: 204]**\n\n**NO Response Body**\n\n----\n\n---\n\n## Setup\n\n### Encryption Keys\n\n---\n\nTo begin downloading the correct OpenSSL needed, you need to head over to\n[this GitHub page](https://github.com/openssl/openssl/wiki/Binaries).\n\nFollow the instructions there to properly download it.\n\nFor Windows (the way I used):\n\n1. Head over to this [website](https://slproweb.com/products/Win32OpenSSL.html). \n    (Available in the GitHub page as well)\n\n2. Download the `EXE` for `Win64 OpenSSL Light` with their latest version.\n3. After installation, run the application `Win64 OpenSSL Command Prompt`\n4. Within the command prompt, make sure you are within the same directory of `src/main/resources/jwt`:\n    ```bash\n    cd \u003cPROJECT-FOLDER\u003e/api/src/main/resources/jwt\n   ```\n5. Run this command to generate a private key:\n    ```bash\n    openssl genpkey -algorithm RSA -out app.key -outform PEM\n   ```\n6. Run this command to generate a public key:\n    ```bash\n    openssl rsa -pubout -in app.key -out app.pub\n    ```\n\n\n#### Concerning Security Considerations\n\nAs of now, the idea of this project was to host it locally \ntherefore no considerable considerations to safe-keep the encryption keys were carried out.\n\nHowever, one such method will be implemented and documented as of then.\n\nIf you already have an idea, then the 2 keys generated above will need to be safe-guarded **and** \nyou need to consider `application.yml` configuration as well.\n\n---\n\n### Database Setup\n\n---\n\nFollow the installation instructions in this [website](https://www.postgresql.org/download/),\nand set-up a database.\n\nThe default one is named `postgres` on port `5432`\n\nMake sure to include the database credentials in the `application.yml`\nby following the steps in this [section](#applicationyml-configuration).\n\n---\n\n### application.yml Configuration\n\n---\n\nTo properly run this API, you must configure your `application.yml` file, which is located in `src/main/resources/`.\n\nHere are a few settings you must make sure are configured correctly:\n\n```yml\n  datasource:\n    # This must be uncommented\n\n    # url: jdbc:postgresql://\u003cHOST\u003e:\u003cPORT\u003e/\u003cDATABASE\u003e          \u003c Here add the URL to access the database (Self-hosted / Docker Compose)\n    # username: \u003cUSERNAME\u003e                                     \u003c Here add your database username \n    # password: \u003cPASSWORD\u003e                                     \u003c Here add your database password        \n\n    # This should remain if you continue to use PostgreSQL\n    driver-class-name: org.postgresql.Driver\n```\n\nThe same should be done here as well:\n\n```yml\nflyway:\n   enabled: true\n   # url: jdbc:postgresql://\u003cHOST\u003e:\u003cPORT\u003e/\u003cDATABASE\u003e          \u003c Here add the URL to access the database (Self-hosted / Docker Compose)             \n   # user: ***                                                \u003c Here add your database username \n   # password: ***                                            \u003c Here add your database password \n   validate-on-migrate: true\n   baseline-on-migrate: true\n   baseline-version: 1\n```\n\nAfter following the [Encryption Keys](#encryption-keys) section, \nyou should have **2** files: `app.key` and `app.pub`.\n\nAdding their classpath here is **important**, but if there are already\nlocated at `src/main/resources/jwt` then there is no need to change this.\n\n```yml\njwt:\n  private-key: classpath:jwt/app.key\n  public-key: classpath:jwt/app.pub\n  ttl: 15m\n```\n\nLeaving `ddl-auto` to be `create` will cause the database to drop tables at\nevery server start, therefore this setting should be unchanged if you are **still developing your schema**.\n\nOtherwise change it to `update` to retain the rows in your tables.\n\n```yml\n    hibernate:\n      ddl-auto: create\n```\n\nIf port *443* is already preoccupied or you prefer another, change it here:\n\n```yml\nserver:\n  port: 443\n```\n\n---\n\n## Project Structure\n```plaintext\n  src/\n   ├───main/\n   │   ├───java/\n   │   │   └───com/acskii/api\n   │   │            ├───config/           # Main configuration beans\n   │   │            ├───enums/            # API Enum Entities\n   │   │            │   └───transactions/       # All entities for Transaction Model\n   │   │            │       ├───method/         # PaymentMethod enum entity\n   │   │            │       │   ├───data        # PaymentMethod Model\n   │   │            │       │   ├───exception   # PaymentMethod Exceptions\n   │   │            │       │   ├───repo        # PaymentMethod Repository\n   │   │            │       │   └───service     # Service layer\n   │   │            │       └───type/           # TransactionType enum entity\n   │   │            │           ├───data        # TransactionType Model\n   │   │            │           ├───exception   # TransactionType Exceptions\n   │   │            │           ├───repo        # TransactionType Repository\n   │   │            │           └───service     # Service layer\n   │   │            │\n   │   │            ├───jwt/              # JWT service beans  \n   │   │            ├───transactions/       \n   │   │            │   ├───controller/   # Transaction API endpoints  \n   │   │            │   ├───data/         # Transaction Models  \n   │   │            │   │   └───dto/      # Transaction Response DTOs  \n   │   │            │   ├───exception/    # Custom exceptions\n   │   │            │   ├───mapper/       # Mappers to DTOs\n   │   │            │   ├───repo/         # Transaction JPA repository\n   │   │            │   └───service/      # Service layer\n   │   │            └───users/\n   │   │                ├───controller/   # User API endpoints  \n   │   │                ├───data/         # User Models \n   │   │                │   └───dto/      # User Response DTOs\n   │   │                ├───exception/    # Custom exceptions\n   │   │                ├───mapper/       # Mappers to DTOs\n   │   │                ├───repo/         # User JPA repository\n   │   │                └───service/      # Service layer\n   │   └───resources/       \n   │        ├── application.yaml          # Main application configuration\n   │        ├───db\n   │        │   └───migration             # Contain database migrations\n   │        └───jwt/                      # Contains OpenSSL keys\n   └───test/                              # Will contain test units (TBD)\n```\n\n---\n\n## How to run\n\n---\n\n### Database\n\n### Steps\n\n1. Clone Repository\n    ```bash\n    git clone git@github.com:acskii/expense-tracker-api.git\n    cd api\n    ```\n   \n\n2. Run the API\n\n   - Compile application and download dependencies using Maven:\n    ```bash\n    ./mvnw clean package\n    ```\n\n    - Run the Spring boot application:\n        ```bash\n        java -jar  .\\target\\api-0.0.1-SNAPSHOT.jar\n        ```\n        **or**\n        ```bash\n        ./mvnw spring-boot:run\n        ```\n\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facskii%2Fexpense-tracker-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facskii%2Fexpense-tracker-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facskii%2Fexpense-tracker-api/lists"}