Files
moeum/API_INTEGRATION_SUMMARY.md
2025-11-14 14:57:34 +00:00

4.9 KiB

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