Seif Mamdouh

📚 Series Overview

This is Part 1 of 3 in the Road to 10x series on building scalable API architecture for voice AI agents.

Part 1 (this article): API Discovery & Type Safety Part 2: Building Scalable Clients & the Result Pattern Part 3: Next.js Routes, Validation & Deployment

TL;DR

Before writing any code, you need to:

Thoroughly test and document every API endpoint you'll use
Create TypeScript interfaces for all data types
Build a foundation of type safety that prevents runtime errors

This approach eliminates surprises in production and gives you a clear roadmap before building your voice AI integration.

Characters for this Series:

👦 Aiden
🧑‍💻 Seify (myself)
🙋 curious audience

Context

👦 Aiden was building a voice AI agent for a real estate company when he ran into a common problem.

During a complex integration with multiple property APIs, he realized his code was becoming a tangled mess of API calls, error handling, and voice response formatting. He had the option of just hard-coding everything, but that wouldn't scale when they added more API providers 🤷

So Aiden messaged me on Slack, saying:

👦 Aiden: "We need a better way to architect these voice AI API integrations. Something that actually scales."
🧑‍💻 Me: "Let me show you the approach I've been working on! 🫡"

The Foundation: Know Before You Build

🙋 "Why not just start coding right away?"

🧑‍💻 "Because that's how you end up rewriting everything when you discover the API behaves differently than you expected. Think of it like building a house - you need to know what materials you're working with before you start construction."

The two foundational steps:

API Discovery - Test every endpoint, understand every response
Type Contracts - Define exact shapes for all data structures

Let's dive in!

Step 1: Test and Document Every API Endpoint First

🧑‍💻 "Before writing any code, I fire up a .rest file and start hitting endpoints to see what I'm working with:"

### Get Properties
GET {{base_url_staging}}/api/properties
Accept: application/json
Authorization: Bearer {{api_token_staging}}

### Get Property Details
GET {{base_url_staging}}/api/properties/{{property_id}}
Accept: application/json
Authorization: Bearer {{api_token_staging}}

### Search Properties with Filters
POST {{base_url_staging}}/api/properties/search
Accept: application/json
Authorization: Bearer {{api_token_staging}}
Content-Type: application/json

{
  "bedrooms": 3,
  "maxPrice": 500000,
  "location": "downtown"
}

🙋 "So you're basically exploring the API like a detective?"

🧑‍💻 "Exactly! I need to know EXACTLY what outputs I'm getting. No surprises in production!"

Why This Matters for Voice AI

When a voice agent crashes mid-conversation because an API returned an unexpected field type, you lose user trust. By testing first:

You discover edge cases early - Empty arrays? Null values? Weird field names?
You document real responses - Not what the docs claim, what you actually get
You understand rate limits - Hit the API repeatedly, see what happens
You find auth quirks - Some APIs need refresh tokens, some expire quickly

Pro tip: Save actual API responses as comments in your .rest file. They become invaluable reference material.

### Expected Response:
# {
#   "properties": [
#     {
#       "prop_id": "abc123",
#       "addr": "123 Main St",
#       "listing_price": "$500,000",  // Note: STRING with $ sign!
#       "bed_rooms": "3"               // Note: Also a STRING!
#     }
#   ],
#   "total": 1,
#   "page": 1
# }

Notice how this API returns numbers as strings? And uses snake_case? You need to know this upfront.

Step 2: Create TypeScript Interfaces for All Data Types

🧑‍💻 "Once I know what the API returns, I create interfaces for everything:"

export interface RealEstateConfig {
  apiKey: string;
  clientId: string;
  clientSecret: string;
  baseUrl?: string;
}

export interface Property {
  id: string;
  address: string;
  price: number;
  bedrooms: number;
  bathrooms: number;
  squareFeet: number;
  images: string[];
}

export interface PropertySearchParams {
  bedrooms?: number;
  minPrice?: number;
  maxPrice?: number;
  location?: string;
  propertyType?: 'house' | 'condo' | 'apartment';
}

export interface RealEstateError {
  error?: string;
  message?: string;
  statusCode?: number;
  details?: any;
}

🙋 "Why all these interfaces?"

🧑‍💻 "Type safety, my friend! When you're building voice AI, you can't afford runtime errors. The agent needs to know exactly what data it's working with."

The Power of Type Contracts

Notice what we did here:

1. External vs Internal Types

The API gave us:

{
  "prop_id": "abc123",      // External: snake_case
  "listing_price": "$500,000"  // External: string with $
}

Our interface defines:

interface Property {
  id: string;        // Internal: camelCase
  price: number;     // Internal: actual number
}

This separation is crucial! You'll transform external → internal in Part 2.

2. Optional vs Required

interface PropertySearchParams {
  bedrooms?: number;      // Optional - users might not specify
  location?: string;      // Optional
  propertyType?: 'house' | 'condo' | 'apartment';  // Optional, but constrained!
}

TypeScript now enforces that if you pass propertyType, it MUST be one of those 3 values. Voice agents can't accidentally send "mansion" or "castle" 🏰

3. Union Types for Enums

propertyType?: 'house' | 'condo' | 'apartment';

This is better than:

propertyType?: string;  // Could be ANYTHING! 😱

Your editor will autocomplete the valid options, and TypeScript will prevent invalid values at compile time.

Benefits You Get Immediately

Autocomplete everywhere - Your editor knows every field
Compile-time errors - Typos caught before running code
Self-documenting code - New devs see exactly what data looks like
Refactoring confidence - Change a field name, TypeScript shows every place that needs updating

🙋 "What about the external API's weird format with snake_case and string prices?"

🧑‍💻 "Great question! That's where the transformation layer comes in. We'll build that in Part 2 when we create the client. For now, we're defining our INTERNAL contract - how WE want to work with this data."

Why This Foundation Matters

Before we move to Part 2, let's reflect on what we've built:

📝 Documented API Endpoints

You know exactly what requests to make
You've seen real responses, not just docs
You understand quirks, limits, and edge cases

🔒 Type-Safe Contracts

Your internal data structures are defined
TypeScript enforces correctness everywhere
Voice agents can't send invalid data

🎯 Clear Separation

External API format (messy, out of your control)
Internal data format (clean, your design)
Transformation layer will connect them (coming in Part 2!)

What's Next?

In Part 2, we'll build the actual client that:

Makes API calls using the endpoints you discovered
Transforms external data → your internal TypeScript interfaces
Implements the Result pattern for type-safe error handling
Handles rate limiting and retries automatically

The foundation is set. Now let's build the architecture! 🚀

Continue to Part 2: Building Scalable Clients →

- Seif 🧑‍💻