--- sidebar_position: 2 title: Unified DataHUB Solution Design --- # Unified DataHUB Solution Design ## DATAHUB Service Module The proposed solution is to introduce a new DataHUB Service Application and Service Module within Service Center. This service will provide a centralized and secure mechanism for extracting data from the existing datasets managed within HOIST HUB Core. ### Application Architecture DataHUB will be implemented as a standalone application, ensuring clear separation of concerns from existing HUB applications. This approach will reduce deployment dependencies and allow DataHUB releases to be delivered independently across TST and PROD environments. A new Application Type will be introduced within the `HoistHubApplication` static entity: ``` DataHUB ``` ### Security and Permissions DataHUB will leverage the existing HUB authorization framework while maintaining its own dedicated permission set for data extraction activities. - A dedicated Service Profile will be introduced, containing only permissions related to data extraction. - Portal Owners will be able to configure and fine-tune the data access granted to each service account. - This model supports the creation of multiple service accounts with different extraction permissions, enabling controlled access to specific datasets and API endpoints. ### Service Account Management DataHUB APIs will be secured using: - Service Account Username and Password authentication. - A valid API Key. Using the HUB user interface, Portal Owner administrators will be able to: - Create and deactivate service accounts. - Assign and manage extraction permissions. - Generate and regenerate API keys. - Control access to DataHUB endpoints. ### API Design DataHUB will expose dedicated API endpoints for each major business entity. For example, the Quotes endpoint will return a structured JSON response containing related quotation data: **Quote Response Structure (QuoteRes)** - `QuoteHeaders` — Collection of quotation headers. - `QuoteLines` — Collection of quotation lines linked to quotation headers. - `QuoteCharges` — Collection of quotation charges linked to quotation headers. - Additional related quotation entities as required. To improve performance and reduce payload sizes, endpoints will support optional inclusion parameters that allow consumers to request only the data required. **Example Request** ``` {baseUrl}/DataHub/Quotes ?lastUpdatedFrom=yyyy-MM-ddTHH:mm:ssZ &includeHeaders=true &includeLines=true &includeCharges=false ``` **Parameter Defaults** - Header-level entities: `true` - Detail-level entities: `false` This approach enables consumers to optimize data transfers while maintaining flexibility in the information returned by each endpoint. :::tip[See also] The finalized endpoint contracts (verified against `hub-dev.hoist.tech`) are documented in [API Overview & Conventions](./overview), [Quotes/Search](./quotes-search), and [Visits/Search](./visits-search). ::: ### Documentation DataHUB will provide comprehensive API documentation through Swagger/OpenAPI, including: - Authentication requirements. - Endpoint definitions. - Request and response schemas. - Permission requirements. - Sample requests and responses. - Error codes and troubleshooting guidance. --- ## Data Set Expansion and Related Entity Exposure The initial DataHUB APIs will expose the primary dataset and its first-level related entities as defined in this proposal. However, additional views or enhancements may be required when Martin Engineering needs access to data from referenced entities beyond the first level. For example, a Quote record may contain only a reference to the customer through `CustomerId`: ``` Quote ├── Quotation No (PK) ├── Customer Id (FK → Customer) ├── Other Quote Attributes... ``` If consumers require customer details such as the customer name, two possible approaches can be considered. ### Option 1 – Nested Related Entity ``` Quote ├── Quotation No (PK) ├── Customer │ ├── Customer Name │ ├── Customer Number │ └── Other Customer Attributes... └── Other Quote Attributes... ``` ### Option 2 – Flattened Response Structure ``` Quote ├── Quotation No (PK) ├── Customer Name ├── Customer Number ├── Other Customer Attributes... └── Other Quote Attributes... ``` The preferred approach will be determined during implementation based on performance considerations, API usability, payload size, and business requirements. Where necessary, additional views and endpoints may be introduced to expose related entity data while maintaining a consistent and scalable API structure.