📝 migrate to api routes usage

[wab]

🚀 API Routes Refactoring Guide: Transform to API-First Architecture

📋 Overview

This comprehensive refactoring guide establishes a systematic approach to transform our React Router v7 application into a true API-first architecture while maintaining our existing framework-native cache strategy.

✅ Current Foundation

• ✅ Working API route: /api/blog with proper cache headers (s-maxage=3600, stale-while-revalidate=86400)
• ✅ Framework-native caching: Headers applied in entry.server.tsx with Vercel-CDN-Cache-Control
• ✅ Cache strategy module: Complete caching infrastructure in app/modules/cache.ts
• ✅ Content API layer: Existing backend functions in app/modules/content/api.ts

🎯 Refactoring Goals

New API Routes

/api/posts         // Blog posts (renamed from /api/blog) 
/api/posts/:slug   // Individual blog posts
/api/stories       // Client stories
/api/stories/:slug // Individual client stories  
/api/search        // Content search
/api/tags          // Available tags

Architecture Transformation

Before: HTML Pages ⟶ Direct Backend Calls ⟶ GitHub API
After: HTML Pages ⟶ API Routes ⟶ GitHub API

📝 Implementation Phases

Phase 1: Core API Routes (6 endpoints)

• Rename existing /api/blog → /api/posts
• Create individual post, stories, search, and tags endpoints
• Follow established patterns for caching and error handling

Phase 2.5: Cache Strategy Cleanup

• 50% code reduction: Simplify cache.ts from 129 → ~60 lines
• Separate concerns: getApiCacheHeaders() vs getHtmlCacheHeaders()
• Remove dead code: Eliminate unused createHybridLoader

Phase 3: Page Refactoring (4 pages)

• Convert HTML pages to call API routes instead of direct backend functions
• Remove duplicate filtering/sorting logic
• Standardize error handling across all consumers

🎯 Key Benefits

Performance & Scalability

• ✅ Single data pipeline: No duplicate logic between pages and APIs
• ✅ Optimized caching: Separate strategies for data (1h+24h) vs HTML (5min+1h)
• ✅ Vercel optimization: Internal API calls are function-to-function

Developer Experience

• ✅ 50%+ code reduction in cache module and page loaders
• ✅ API-first design: External consumers get identical data as HTML pages
• ✅ Better maintainability: Single source of truth for data transformations
• ✅ Standard patterns: Clean React Router loaders replacing complex wrappers

Future-Ready Architecture

• ✅ External API consumers: Mobile apps, webhooks, integrations
• ✅ Progressive enhancement: Foundation for real-time features with SWR
• ✅ Consistent responses: Unified JSON format across all consumers

📊 Success Metrics

1. Zero direct backend calls from HTML pages
2. Preserved cache performance (same header validation)
3. 50%+ code reduction in complexity
4. No regression in page load times
5. Identical response format for internal/external API consumers

🛠 Implementation Strategy

The guide provides:

• Complete code templates for all API routes
• Step-by-step cache cleanup instructions
• Testing protocols for each phase
• Exact patterns for page refactoring
• Success criteria for validation

🔗 References

• Working Example: app/routes/api.blog._index.tsx (to be renamed)
• Cache Module: app/modules/cache.ts
• Content API: app/modules/content/api.ts
• Entry Server: app/entry.server.tsx

---

This refactoring transforms our application into a modern, API-first architecture while maintaining our excellent cache performance and adding powerful new capabilities for external integrations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
ocobo	Ready	Preview	Aug 22, 2025 5:08pm