feat(spring-sample): Reorganize Hiero API endpoints into domain-driven controllers

[Twiineenock]

Overview

This PR initiates the transition from a monolithic API structure to a modular, domain-driven architecture for the Hiero Enterprise Spring Boot sample. By introducing dedicated controllers and structured DTOs, we improve the maintainability, discoverability, and scalability of the API surface.

Core Architectural Changes

• Domain Segregation: Replaced the legacy HieroEndpoint.java with domain-specific controllers (AccountController, BlockController).
• Structured Data Handling: Introduced a new dto package to manage request and response payloads, ensuring clear API contracts.
• Spring Boot 3 Optimization: Implemented explicit naming for @PathVariable and @RequestBody to ensure compatibility with modern Spring reflection standards.

Endpoints Implemented

1. Account Resource (/api/v1/hiero/accounts)

• POST /: Creates a new Hiero account (returns accountId, publicKey, and privateKey).
• PUT /: Updates account metadata such as memos or keys.
• DELETE /: Deletes a Hiero account using its private key.
• GET /balance/{accountId}: Fetches the real-time Hbar balance from the network.
• GET /info/{accountId}: Retrieves detailed account metadata from the Hiero Mirror Node.

2. Block Resource (/api/v1/hiero/blocks)

• GET /: Returns a paginated list of the most recent blocks processed by the network.
• GET /{number}: Fetches detailed information for a specific block by its sequence number.

Verification Results

• ✅ Account Lifecycle: Verified Create -> Update -> Delete flow on Hedera Testnet.
• ✅ Mirror Node Integration: Confirmed successful retrieval of block and account info.

Fungible Token Resource Endpoints

• POST /api/v1/hiero/fungible-token — Create a new fungible token.
• GET /api/v1/hiero/fungible-token/{tokenId} — Retrieve detailed information and metadata for a specific token.
• POST /api/v1/hiero/fungible-token/{tokenId}/mint — Mint additional units of a token to the treasury.
• POST /api/v1/hiero/fungible-token/{tokenId}/transfer — Transfer tokens between accounts (requires sender credentials).

NFT Resource Implementation

Added support for core NFT lifecycle operations by integrating the NftClient and NftRepository services. This addition includes:

• POST /api/v1/hiero/nfts: Create a new NFT collection.
• GET /api/v1/hiero/nfts/{nftId}: Retrieve NFT collection metadata.
• POST /api/v1/hiero/nfts/{nftId}/mint: Mint unique NFT instances.
• GET /api/v1/hiero/nfts/{nftId}/serial/{serial}: Fetch a specific NFT instance.
• POST /api/v1/hiero/nfts/{nftId}/transfer: Securely transfer NFT ownership.

All endpoints have been verified on the testnet and utilize dedicated request DTOs for structured data handling.

Consensus (Topic) Resource

Exposes full lifecycle management for Hiero Topics and HCS messages.

• POST /api/v1/hiero/topics: Create a new topic.
• PUT /api/v1/hiero/topics: Update topic configuration (memo, keys).
• DELETE /api/v1/hiero/topics/{topicId}: Delete a topic.
• POST /api/v1/hiero/topics/message: Submit a message to a topic.
• GET /api/v1/hiero/topics/{topicId}/info: Retrieve topic metadata via Mirror Node.
• GET /api/v1/hiero/topics/{topicId}/message: Retrieve all messages for a topic.
• GET /api/v1/hiero/topics/{topicId}/message/{sequenceNumber}: Retrieve a specific message by sequence number.

Network Resource

Provides global network-wide information including rates, fees, and supply statistics.

• GET /api/v1/hiero/network/exchange-rate: Retrieve current and next HBAR/USD exchange rates.
• GET /api/v1/hiero/network/fee: Retrieve a comprehensive list of network transaction fees.
• GET /api/v1/hiero/network/stake: Retrieve network staking reward and pool information.
• GET /api/v1/hiero/network/supplies: Retrieve HBAR supply details (released and total supply).

File Resource

Manages Hedera on-chain files including creation, updates, and metadata queries.

• POST /api/v1/hiero/files: Create a new file (supports Base64 content).
• POST /api/v1/hiero/files/{fileId}: Update file content or expiration time.
• DELETE /api/v1/hiero/files/{fileId}: Delete an existing file.
• GET /api/v1/hiero/files/{fileId}/content: Retrieve file content as a Base64 string.
• GET /api/v1/hiero/files/{fileId}/size: Retrieve the current size of the file in bytes.

[Twiineenock]

The interactive API documentation can now be accessed at http://localhost:8080/swagger-ui.html during development

CC @Ndacyayisenga-droid , @manishdait, @hendrikebbers

[hendrikebbers]

From my point of view this is not a sample. It should be a project on its own that provides REST based Access to a Hiero network. In the end it is a REST proxy for Hiero.

What we should do:

• Request a new repo at https://github.com/hiero-hackers
• mention this PR in the request and say that I suggested it
• The repo should be called hiero-enterprise-proxy
• Goal of the repo is to provide a full REST based proxy for all functionalities.
• The code you have started here would be the initial code of the repo

Very good work!

[Twiineenock]

From my point of view this is not a sample. It should be a project on its own that provides REST based Access to a Hiero network. In the end it is a REST proxy for Hiero.

What we should do:

• Request a new repo at https://github.com/hiero-hackers
• mention this PR in the request and say that I suggested it
• The repo should be called hiero-enterprise-proxy
• Goal of the repo is to provide a full REST based proxy for all functionalities.
• The code you have started here would be the initial code of the repo

Very good work!

Thanks @hendrikebbers
That's a clear direction! on it!

[Twiineenock]

hiero-hackers/governance#11

CC @hendrikebbers @Ndacyayisenga-droid