139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
# API Integration Summary
|
|
|
|
## Overview
|
|
Successfully integrated the frontend SPA with the backend API server using Kiota API client and React Query for data fetching and state management.
|
|
|
|
## Changes Made
|
|
|
|
### 1. API Client Setup
|
|
- **File**: `src/lib/apiClient.ts`
|
|
- Created a centralized API client using Kiota's `DefaultRequestAdapter`
|
|
- Configured with `AnonymousAuthenticationProvider` for now (can be upgraded to authenticated requests later)
|
|
- Base URL configured to: `https://moeum.dahyeon.us/`
|
|
|
|
### 2. React Query Hooks
|
|
- **File**: `src/hooks/useApi.ts`
|
|
- Created custom hooks for API calls:
|
|
- `useSiteHeader()` - Fetches site header navigation data
|
|
- `useTaxonomyChildren(taxonomyId)` - Fetches child items for a taxonomy
|
|
- `useArticle(slug)` - Fetches article content by slug
|
|
- `useArticleTaxonomyPath(slug)` - Fetches taxonomy path for an article
|
|
|
|
### 3. React Query Provider
|
|
- **File**: `src/main.tsx`
|
|
- Added `QueryClientProvider` to wrap the app
|
|
- Configured with:
|
|
- 5-minute stale time
|
|
- Disabled refetch on window focus
|
|
|
|
### 4. Header Component Updates
|
|
- **File**: `src/components/Header.tsx`
|
|
- Replaced hardcoded menu items with dynamic data from `getSiteHeader` API
|
|
- Menu structure mapping:
|
|
- API `label` → Menu button label (e.g., "Documentation", "Training")
|
|
- API `key` → Internal identifier for menu state
|
|
- API `sections[].headline` → Dropdown section headers (e.g., "DOCUMENTATION")
|
|
- API `sections[].taxonomies[].label` → Dropdown menu items
|
|
- API `sections[].taxonomies[].taxonomyId` → Click handler for navigation
|
|
- Added `onTaxonomyClick` prop to handle taxonomy navigation
|
|
|
|
### 5. Sidebar Component Updates
|
|
- **File**: `src/components/Sidebar.tsx`
|
|
- Replaced hardcoded navigation with dynamic taxonomy child items
|
|
- Fetches data from `/v1/taxonomies/{id}/child-items` endpoint
|
|
- Recursive rendering of nested menu items
|
|
- Mapping:
|
|
- API `items[].title` → Menu item label
|
|
- API `items[].href` → Article slug for navigation
|
|
- API `items[].children` → Nested submenu items
|
|
- Added `onArticleClick` prop to handle article selection
|
|
|
|
### 6. MainContent Component Updates
|
|
- **File**: `src/components/MainContent.tsx`
|
|
- Replaced hardcoded article content with dynamic data from API
|
|
- Fetches data from `/v1/articles/{slug}` endpoint
|
|
- Displays:
|
|
- Article title
|
|
- Last updated date
|
|
- Article content (rendered as HTML)
|
|
- Added loading and error states
|
|
- Shows placeholder message when no article is selected
|
|
|
|
### 7. App State Management
|
|
- **File**: `src/App.tsx`
|
|
- Added state for:
|
|
- `currentTaxonomyId` - Tracks selected taxonomy
|
|
- `currentArticleSlug` - Tracks selected article
|
|
- Added handlers:
|
|
- `handleTaxonomyClick` - Navigates to documentation page and loads taxonomy
|
|
- `handleArticleClick` - Loads article content
|
|
- Props flow: App → DocumentationPage → Sidebar/MainContent
|
|
|
|
### 8. DocumentationPage Updates
|
|
- **File**: `src/components/DocumentationPage.tsx`
|
|
- Updated to accept and pass through:
|
|
- `taxonomyId` → Sidebar
|
|
- `articleSlug` → MainContent
|
|
- `onArticleClick` → Sidebar
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
1. User clicks menu item in Header
|
|
↓
|
|
2. Header calls onTaxonomyClick(taxonomyId)
|
|
↓
|
|
3. App updates currentTaxonomyId state
|
|
↓
|
|
4. Sidebar fetches /v1/taxonomies/{id}/child-items
|
|
↓
|
|
5. User clicks article in Sidebar
|
|
↓
|
|
6. Sidebar calls onArticleClick(slug)
|
|
↓
|
|
7. App updates currentArticleSlug state
|
|
↓
|
|
8. MainContent fetches /v1/articles/{slug}
|
|
↓
|
|
9. Article content is displayed
|
|
```
|
|
|
|
## API Endpoints Used
|
|
|
|
1. **GET /v1/contents/site-header**
|
|
- Returns array of site header configurations
|
|
- Used by: Header component
|
|
|
|
2. **GET /v1/taxonomies/{id}/child-items**
|
|
- Returns hierarchical menu structure for a taxonomy
|
|
- Used by: Sidebar component
|
|
|
|
3. **GET /v1/articles/{slug}**
|
|
- Returns article content and metadata
|
|
- Used by: MainContent component
|
|
|
|
4. **GET /v1/articles/{slug}/taxonomy-path** (prepared but not yet used)
|
|
- Returns taxonomy path for breadcrumb navigation
|
|
- Can be used for enhanced breadcrumb display
|
|
|
|
## Dependencies Added
|
|
|
|
- `@tanstack/react-query@^5.90.8` - Already in package.json
|
|
- `@microsoft/kiota-bundle@^1.0.0-preview.99` - Already in package.json
|
|
- `@types/react-dom` - Added for TypeScript support
|
|
|
|
## Testing
|
|
|
|
The application is now running at `http://localhost:3420` and ready for testing with your API server.
|
|
|
|
## Next Steps (Optional Enhancements)
|
|
|
|
1. **Authentication**: Replace `AnonymousAuthenticationProvider` with proper auth
|
|
2. **Error Handling**: Add more detailed error messages and retry logic
|
|
3. **Caching**: Fine-tune React Query cache settings based on data update frequency
|
|
4. **Breadcrumbs**: Use `useArticleTaxonomyPath` to show full navigation path
|
|
5. **Search**: Implement search functionality using the search input in Sidebar
|
|
6. **Loading Skeletons**: Replace simple loading text with skeleton screens
|
|
7. **Optimistic Updates**: Add optimistic UI updates for better UX
|
|
8. **Offline Support**: Add service worker for offline article reading
|