Quick Start - Zod API Validation

30-Second Overview

Your Constellation frontend now has complete type-safe API validation for all FastAPI endpoints. Every API call is automatically validated against Zod schemas.

Installation

✅ Already done! No additional setup needed.

Basic Usage

1. Import and Use

import { getConstellations } from "@/src/lib/api";

const constellations = await getConstellations();
// Type: ConstellationPublic[]
// Automatically validated ✓

2. Error Handling

try {
  const constellations = await getConstellations();
} catch (error) {
  console.error(error.message);
  // "Get Constellations validation failed: id: Invalid uuid, ..."
}

3. Form Validation

import { validateRequest } from "@/src/lib/validation";
import { ConstellationCreate } from "@/src/lib/schemas/api";

const validated = validateRequest(formData, ConstellationCreate);
// Throws if invalid, returns typed data if valid

Common Patterns

Fetch Data

import { getConstellations } from "@/src/lib/api";

// In component
const [constellations, setConstellations] = useState([]);
useEffect(() => {
  getConstellations().then(setConstellations);
}, []);

Create Data

import { createConstellation } from "@/src/lib/api";

await createConstellation({
  name: "My Project",
  description: "A great project"
});

Update Data

import { updateConstellation } from "@/src/lib/api";

await updateConstellation(id, {
  name: "Updated Name"
});

Delete Data

import { deleteConstellation } from "@/src/lib/api";

await deleteConstellation(id);

Admin Operations

import { getDashboardStats, getAnalytics } from "@/src/lib/admin-api";

const stats = await getDashboardStats();
const analytics = await getAnalytics({ period: "30d" });

API Reference

Core Endpoints

• getConstellations() - List all
• getConstellation(id) - Get one
• createConstellation(data) - Create
• updateConstellation(id, data) - Update
• deleteConstellation(id) - Delete

Available for: Constellations, Collections, Users, YDocs, Assets, Maps, GlossaryTerms

Admin Endpoints

• getDashboardStats() - Stats
• getDashboardActivity() - Activity log
• getDashboardAlerts() - System alerts
• getDashboardUsers(query) - User list
• getDashboardConstellations(query) - Constellation list
• getAnalytics(query) - Analytics data

Validation Utilities

• validateRequest(data, schema) - Validate input
• validateResponse(data, schema) - Validate response
• validateAxiosResponse(response, schema) - Combined
• tryValidateResponse(data, schema) - Safe (no throw)

Where to Find Things

What	Where
API Wrappers	src/lib/api.ts
Admin API	src/lib/admin-api.ts
Schemas	src/lib/schemas/api.ts
Admin Schemas	src/lib/schemas/admin.ts
Validation Utils	src/lib/validation.ts
Full Documentation	docs/ZOD_API_VALIDATION.md

Migrating Existing Code

Before

const response = await apiClient.get("/constellations");
const constellations: any[] = response.data;

After

import { getConstellations } from "@/src/lib/api";
const constellations = await getConstellations();
// Type is ConstellationPublic[]

TypeScript Support

All types are automatically inferred:

import { getConstellations } from "@/src/lib/api";

const constellations = await getConstellations();

// TypeScript knows:
constellations.forEach(c => {
  c.id      // ✓ string
  c.name    // ✓ string
  c.foo     // ✗ Error: property doesn't exist
});

Custom Schemas

Want to add new schemas? Just add to src/lib/schemas/api.ts:

export const MyNewSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
});
export type MyNew = z.infer<typeof MyNewSchema>;

Then use in src/lib/api.ts:

export async function getMyData(): Promise<MyNew> {
  const response = await apiClient.get("/my-endpoint");
  return validateAxiosResponse(response, MyNewSchema, "Get My Data");
}

Performance

• ✅ Zero overhead in production (tree-shakeable)
• ✅ Validation only on API boundaries
• ✅ No runtime cost for type checking

Need Help?

• Full guide: docs/ZOD_API_VALIDATION.md
• Examples: See usage in existing components
• Schema reference: Check src/lib/schemas/api.ts

---

You're ready to go! Start replacing raw apiClient calls with the typed wrappers for full type safety. 🚀