My portfolio fetches NASA's Daily Space Photo - and never fails!

I integrated NASA's Astronomy Picture of the Day (read about it) into my portfolio.

• SPOILER ALERT: Contains rate limiting, fallback scraping, modular architecture, and production-grade error handling that never leaves users hanging.

---

The Vision: Bringing Space to My Portfolio

My portfolio (luisfaria.dev) runs a full-stack MERN application with authentication, a chatbot, and a GraphQL API. I wanted to add something unique — something that would genuinely delight users while showcasing real-world API integration skills.

Between terms of my Master's Degree, I had a few weeks off. Perfect vacation project, right? BTW, I'm open-sourcing the whole thing — check it out! mastersSWEAI repo

The idea: A floating action button that reveals NASA's daily Astronomy Picture of the Day (APOD). Simple concept, complex execution.

The User Experience

Click the NASA rocket button: 👉 luisfaria.dev

• Anonymous users: Get today's APOD instantly — no login required
• Authenticated users: Browse NASA's entire archive dating back to 1995
• Rate limiting: 5 requests/hour per user to protect the NASA API quota
• Resilience: If NASA's API fails, automatic HTML scraping fallback kicks in

Here's exactly what happens when someone clicks that rocket button:

👉 See the image in HD

---

The Challenge: External APIs Are Unreliable

Integrating third-party APIs sounds straightforward — until reality hits:

The goal: Build an integration that:

1. Handles every failure mode gracefully
2. Never crashes the server
3. Falls back automatically when NASA is down
4. Logs everything for debugging
5. Provides structured errors to clients

Spoiler: NASA's API went down during development. More than once.

---

The Architecture: Layered Resilience

Here's the system I designed:

Browser (Next.js/React)
    ↓
GraphQL API (Apollo Server)
    ↓
APOD Service Layer
    ├──→ NASA API (primary, with retries + timeout)
    └──→ HTML Scraping Fallback (when API fails)
         ↓
    Redis Rate Limiter (atomic Lua scripts)
         ↓
    MongoDB (cache successful responses)

Key Architectural Decisions (3 of them!)

1. GraphQL Shield for Authorization

• getTodaysApod is public (no login)
• getApodByDate requires authentication (prevents abuse)

2. Modular Service Design

src/services/apod/
├── index.ts              # Barrel export
├── apod.service.ts       # Orchestrator (API + fallback)
├── apod.api.ts           # NASA API client
├── apod.fallback.ts      # HTML scraping fallback
├── apod.errors.ts        # Typed error codes
├── apod.types.ts         # Zod schemas, TypeScript types
└── apod.constants.ts     # URLs, timeouts, retry config

3. Shared Error Handling Infrastructure Instead of copy-pasting try/catch blocks across every resolver (we've all been there), I built a reusable error handler:

// src/utils/errors/graphqlErrors.ts
export function createErrorHandler<TCode, TError>(
  mapErrorCode: (code: TCode) => ErrorCode,
  isServiceError: (error: unknown) => error is TError,
  defaultMessage: string
) {
  return function withErrorHandling<T>(
    fn: () => Promise<T>, 
    operationName: string
  ): Promise<T>
}

Now any service can use it:

// APOD resolver (34 lines total)
export const ApodQueries = {
  getTodaysApod: async (_, __, context) =>
    withApodErrorHandling(
      () => fetchApod({ context: { userId: context.user?.id } }),
      'getTodaysApod'
    ),

  getApodByDate: async (_, args, context) => {
    if (!context.user) {
      throw Errors.unauthenticated('Authentication required');
    }
    return withApodErrorHandling(
      () => fetchApod({ date: args.date, context: { userId: context.user.id } }),
      'getApodByDate'
    );
  },
};

---

The Journey: 8 Issues, 40+ Commits, 1 Production Feature

This didn't work on the first try. Or the fifth. Here's the honest implementation timeline:

Tracked in: Epic v2.4 - APOD Feature All 40+ commits to (apod) feature

Phase 1: Foundation (Issues #61-65)

Frontend: NASA-Branded Floating Action Button

Built ApodFab.tsx following the same pattern as the existing GogginsFab component:

• Circular button with NASA gradient border (linear-gradient(135deg, #0B3D91, #FC3D21, #1E90FF))
• Rocket icon with blue pulse aura effect
• Radix UI tooltip: "Astronomy Picture of the Day"
• Accessible (ARIA labels, keyboard navigation)
• Light/dark mode support

Frontend: APOD Dialog Component

Created ApodDialog.tsx with:

• Date display with calendar icon
• Image/video player (handles both media types)
• Copyright attribution
• External link to NASA APOD website
• "Powered by NASA Open APIs" footer

Backend: Configuration & Validation

Set up NASA API credentials:

// backend/src/config/config.ts
interface Config {
  nasaApiKey: string;
}

const requiredEnvVars = ['NASA_API_KEY', ...];

Server refuses to start without NASA_API_KEY — fail fast, no silent surprises.

---

Phase 2: NASA API Client (Issue #66)

Zod Schema for Runtime Validation

NASA's API returns JSON, but not all fields are guaranteed:

// src/validation/schemas/apod.schema.ts
export const apodResponseSchema = z.object({
  copyright: z.string().optional(),
  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  explanation: z.string().min(1),
  media_type: z.enum(['image', 'video', 'other']),  // 'other' was missing initially!
  title: z.string().min(1),
  url: z.string().url().optional(),  // Not provided for media_type: "other"
  hdurl: z.string().url().optional(),
  apod_url: z.string().url().optional(),  // Computed field
});

export type ApodResponse = z.infer<typeof apodResponseSchema>;

NASA API Service with Retries

Built apod.api.ts with:

• Exponential backoff retries (3 attempts)
• 8-second timeout per request
• AbortController for proper cleanup
• Structured logging (latency, status code, userId)

export async function fetchApodFromApi(
  url: string,
  context?: ApodRequestContext
): Promise<ApodResponse> {
  const startTime = Date.now();
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);

  try {
    const response = await fetch(url, {
      signal: controller.signal,
      headers: { 'User-Agent': 'luisfaria.dev/1.0' },
    });

    if (!response.ok) {
      throw new ApodServiceError(
        `NASA API error: ${response.status}`,
        response.status === 429 ? 'RATE_LIMITED' : 'NASA_API_ERROR',
        response.status
      );
    }

    const data = await response.json();
    const validated = apodResponseSchema.parse(data);

    logger.info('NASA API request successful', {
      latencyMs: Date.now() - startTime,
      date: validated.date,
      userId: context?.userId,
    });

    return validated;
  } catch (error) {
    // Error mapping logic...
  } finally {
    clearTimeout(timeoutId);
  }
}

---

Phase 3: The Hard Part — Failures & Fallbacks (aka scars earned)

This is where production engineering got real. Here's every bug I hit:

Bug #2 was the game-changer. When NASA's API returned 504, users saw blank screens. Not acceptable. The fix: automatic HTML scraping fallback — if the API is down, scrape the website directly.

---

Phase 4: HTML Scraping Fallback (Issue #78)

When the NASA API fails, the service automatically scrapes the official APOD website. Users never know the difference:

// src/services/apod/apod.fallback.ts
export async function fetchApodHtmlFallback(
  date?: string
): Promise<ApodResponse> {
  const url = date 
    ? `https://apod.nasa.gov/apod/ap${formatDateForApodUrl(date)}.html`
    : 'https://apod.nasa.gov/apod/astropix.html';

  const html = await fetch(url).then(res => res.text());
  const $ = cheerio.load(html);

  // Parse structured data
  const title = $('center:first b:first').text().trim();
  const explanation = $('center:first p:last').text().trim();
  const imageUrl = $('center:first img').attr('src');

  return {
    date: date || new Date().toISOString().split('T')[0],
    title,
    explanation,
    url: imageUrl,
    media_type: 'image',
    apod_url: url,
    // ... rest of fields
  };
}

Orchestration in apod.service.ts:

export async function fetchApod(options = {}): Promise<ApodResponse> {
  try {
    return await fetchApodFromApi(buildApiUrl(options), options.context);
  } catch (error) {
    if (shouldFallback(error)) {
      logger.warn('NASA API failed, falling back to HTML scraping', { error });
      return await fetchApodHtmlFallback(options.date);
    }
    throw error;
  }
}

Users never see errors — they just get the APOD, regardless of which method worked. That's the whole point.

---

Phase 5: Shared Error Handling Infrastructure (Issue #79)

Before refactor: Each resolver had 30+ lines of try/catch boilerplate. Copy-paste engineering at its worst.

After refactor:

• Created src/utils/errors/graphqlErrors.ts with reusable utilities
• Error factories for common cases: Errors.unauthenticated(), Errors.forbidden(), Errors.notFound()
• Generic createErrorHandler() wrapper generator
• Service-specific error mappers (e.g., withApodErrorHandling)

Impact:

• Resolvers went from 103 lines to 34 lines
• Single place to add new error codes
• Error mapping lives with service logic (where it belongs)
• Other features can reuse the same pattern — and they already do

---

Key Engineering Lessons

Five production-grade patterns I learned (the hard way) from building APOD:

1. Always Have a Fallback

External APIs fail. Network timeouts happen. DNS breaks. If your feature depends on a third-party service, you need a backup plan — full stop:

• Primary: NASA JSON API (fast, structured)
• Fallback: HTML scraping (slower, but always works)
• User experience: Seamless — they never know which method was used

2. Validate External Data at Runtime

TypeScript types don't protect you against API changes. NASA's schema evolved mid-development — they added media_type: "other" for interactive content, which broke my Zod schema mid-sprint.

Solution: Runtime validation with Zod catches schema drift before it crashes the server.

const validated = apodResponseSchema.parse(data);  // Throws if schema mismatch

3. DRY Principle for Error Handling

Don't duplicate try/catch blocks across resolvers. We've all done it. It's technical debt from day one. Extract shared error handling into reusable utilities:

// Before: 30 lines of boilerplate per resolver
// After: 3 lines + shared error handler
return withApodErrorHandling(
  () => fetchApod({ date: args.date, context }),
  'getApodByDate'
);

4. Modular Services Are Testable Services

Splitting the monolithic apod.ts into focused modules made testing trivial — and debugging even more so:

src/services/apod/
├── apod.service.ts       # Orchestration (API + fallback)
├── apod.api.ts           # NASA API client
├── apod.fallback.ts      # HTML scraping
├── apod.errors.ts        # Typed errors
├── apod.types.ts         # Zod schemas
└── apod.constants.ts     # Config

Each module has a single responsibility. Tests mock at the module boundary, not the entire service.

5. Log Everything for Observability

Every NASA API request logs:

• Latency (latencyMs)
• User context (userId)
• Success/failure status
• Error codes and details

When bugs happen in production (and they will), structured logs are your debugging lifeline.

logger.info('NASA API request successful', {
  latencyMs: 142,
  date: '2026-02-18',
  userId: 'user_xyz',
});

---

Results

Real-World Reliability

During a 72-hour period where NASA's API had intermittent 504 errors:

• Primary API success rate: 78%
• Fallback activation: 22%
• User-facing errors: 0%

Users never knew NASA's API was struggling. The fallback handled it seamlessly — that's the whole point of building resilient systems.

---

Tech Stack

---

Future Roadmap

The current implementation is production-ready, but there's always room to grow. Here are 5 ideas — feel free to add yours in the comments!

Idea #1: Database Caching Layer

Right now, every request hits NASA's API (or HTML fallback). Next iteration:

• Cache successful responses in MongoDB
• Return cached APOD if date already fetched
• Reduce API quota usage by 80%
• Instant response for popular dates

Idea #2: Admin Dashboard

GraphQL mutations to manually refresh/delete cached APODs:

mutation RefreshApod($date: String!) {
  refreshApod(date: $date) { date, title }
}

Idea #3: WebSocket Push Updates

Use GraphQL subscriptions to push new APODs to connected clients when they become available at midnight UTC.

Idea #4: Zero-Cold-Start: Daily Cron + Redis 24h Cache

Right now, the first user of the day triggers a live NASA API call. That's ~200-500ms of cold latency — acceptable, but not great.

The plan: a daily cron job fires at 00:01 UTC, fetches today's APOD proactively, and stores it in Redis with a 24h TTL. Every subsequent request that day gets a cache hit — sub-10ms response, zero external calls.

// Pseudocode: src/jobs/apodDaily.ts
export async function warmApodCache() {
  const today = new Date().toISOString().split('T')[0];
  const cacheKey = `apod:${today}`;

  // Already warm? Skip.
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  // Fetch fresh from NASA
  const apod = await fetchApod({ date: today });

  // Cache for exactly 24h (expires at midnight UTC)
  const secondsUntilMidnight = getSecondsUntilMidnightUTC();
  await redis.setex(cacheKey, secondsUntilMidnight, JSON.stringify(apod));

  logger.info('APOD cache warmed', { date: today, ttl: secondsUntilMidnight });
  return apod;
}

The cron schedule via node-cron:

// Fires at 00:01 UTC every day
cron.schedule('1 0 * * *', warmApodCache, { timezone: 'UTC' });

The resolver then checks Redis first before ever hitting NASA:

getTodaysApod: async (_, __, context) => {
  const today = new Date().toISOString().split('T')[0];
  const cacheKey = `apod:${today}`;

  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);        // ⚡ <10ms

  return withApodErrorHandling(                 // 🐌 200-500ms
    () => fetchApod({ context: { userId: context.user?.id } }),
    'getTodaysApod'
  );
},

Expected impact:

The key insight: Redis TTL auto-expires the cache exactly when it stops being valid. No manual invalidation. No stale data. Just fast for 99% of requests.

Idea #5: Analytics Dashboard

Track:

• Most popular APOD dates
• Fallback usage percentage
• Average response time (API vs. fallback)
• Rate limit triggers per user

---

Key Takeaways

Building production-grade API integrations is 20% "get it working" and 80% "handle when it doesn't work."

Five principles that made APOD production-ready:

1. Graceful degradation — Fallbacks ensure users never see errors
2. Runtime validation — Zod catches schema drift before it crashes
3. Modular architecture — Focused modules are easier to test and maintain
4. Shared error handling — DRY principle for GraphQL resolvers
5. Observability — Structured logs make debugging trivial

---

Try It Yourself

The full APOD implementation is open source:

---

Let's Connect!

Building this NASA integration taught me more about production engineering than any tutorial could. Every failure mode I hit — 504 timeouts, schema drift, rate limits, DNS caching — is something I'll face again in enterprise systems. And now I know how to handle it.

If you're working with:

• GraphQL APIs and error handling patterns
• Third-party API integrations with fallback strategies
• Next.js + Node.js full-stack applications
• Production-grade TypeScript architectures

I'd love to connect and trade war stories:

• LinkedIn: linkedin.com/in/lfariabr
• GitHub: github.com/lfariabr
• Portfolio: luisfaria.dev

---

Tech Stack Summary:

---

Built with ☕, 40+ commits, and a healthy fear of blank screens by Luis Faria

Whether it's concrete or code, structure is everything.