Direct API Fetching
Relevant source files
The following files were used as context for generating this wiki page:
Direct API Fetching in the @cellarnode/beverage-utils library refers to the mechanism by which classification data is retrieved from the CellarNode public API and transformed into a local lookup structure. This system allows applications to obtain the most up-to-date industry-standard beverage classifications for use in UI components and data processing.
The system is designed around a single endpoint that provides a hierarchical structure of categories and subtypes. Framework-specific adapters (React, Vue, and Angular) wrap this fetching logic using TanStack Query to provide standardized caching, error handling, and state management across different frontend environments.
Sources: README.md:10-18, src/react/use-beverage-label-map.ts:8-19
API Endpoint and Response Structure
The library interacts with a specific public endpoint to retrieve beverage classifications. The data returned is a JSON object containing a jsonData wrapper with an array of beverage categories.
| Detail | Value |
|---|---|
| Endpoint Path | /api/v1/classifications/beverage-types |
| Method | GET |
| Base URL | Configurable (e.g., https://api.cellarnode.com) |
| Primary Data Key | jsonData |
Sources: README.md:139-142, src/react/use-beverage-label-map.ts:11-14
Data Model
The API returns a BeverageClassification object. Each category within this object can contain multiple subtypes, and both levels include unique identifiers used for mapping.
This diagram shows the hierarchical relationship of the data retrieved from the API.
Sources: src/types.ts:1-15, README.md:144-162
Fetching Logic and Transformation
The fetching process involves making an asynchronous request, validating the response, and then passing the raw data into a transformation function.
Transformation Process
Once the raw JSON is fetched, it is processed by the buildLabelMap function. This function iterates through categories and subtypes to create three types of keys in a flat LabelMap object:
- Category ID: Maps directly to the category name.
- Subtype ID: Maps to the subtype name (last-write-wins for duplicates).
- Composite Key: Uses the format
category:subtypeto ensure unambiguous lookups.
Sources: src/label-map.ts:5-15, README.md:21-31
Execution Flow
The following sequence diagram illustrates the flow from a framework component request to the resulting transformed LabelMap.
This diagram visualizes the data flow from the initial request to the internal transformation of API results.
Sources: src/react/use-beverage-label-map.ts:10-18, README.md:128-135
Framework Implementation
The library provides standardized "Options" and "Hooks/Services" for different frameworks. All framework implementations share a staleTime: Infinity configuration, as classification data is considered static for the duration of a session.
Implementation Patterns
| Framework | Implementation Method | Internal Utility |
|---|---|---|
| React | useBeverageLabelMap(apiBaseUrl) | useQuery |
| Vue | useBeverageLabelMap(apiBaseUrl) | useQuery |
| Angular | injectBeverageLabelMap(apiBaseUrl) | injectQuery |
Sources: src/react/use-beverage-label-map.ts:22-24, src/vue/use-beverage-label-map.ts:22-24, src/angular/beverage-label-map.service.ts:21-23
Manual Fetching
For environments without a supported framework (e.g., Node.js or vanilla JS), the API can be fetched directly using the standard fetch API and manually processed.
const res = await fetch(`${baseUrl}/api/v1/classifications/beverage-types`);
const { jsonData } = await res.json();
const map = buildLabelMap(jsonData);
Sources: README.md:128-135
Summary
Direct API Fetching serves as the bridge between the CellarNode classification database and the local application. By centralizing the fetching logic in beverageLabelMapOptions and the transformation logic in buildLabelMap, the system ensures that ambiguous beverage subtypes (like "Red") are correctly identified through composite keys while maintaining a simple interface for developers.
Sources: README.md:21-25, src/react/use-beverage-label-map.ts:8-10