API Overview

BuildAppsWith offers a comprehensive suite of APIs with standardized response patterns, full type safety, and consistent error handling across all domains.

🎯 API Standardization

All BuildAppsWith APIs follow the StandardApiResponse pattern, ensuring consistent, predictable interactions:

interface StandardApiResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: ApiError;
  pagination?: PaginationInfo;
  message?: string;
}

Key Benefits:

✅ Consistent Response Structure across all endpoints
✅ Type Safety with full TypeScript support
✅ Predictable Error Handling with standardized error codes
✅ Component Integration with flattened data structures
✅ Marketplace Compatibility following proven patterns

API Organization

Our APIs follow a domain-driven design pattern, with clear separation between:

Client-side API Functions: Located in lib/[domain]/api.ts files, these functions handle client-side API calls to the backend.
Server-side Implementation: Located in API routes and server actions, these implement the actual business logic.
Standardized Responses: All endpoints return StandardApiResponse<T> format

Available APIs

Domain	Description	Documentation	Status
Marketplace	Builder discovery and marketplace interactions	Marketplace API	✅ Standardized
Profile	User and builder profile management	Profile API	✅ Standardized
Auth	Authentication and authorization APIs	Auth API	🔄 Migration Ready
Payment	Payment processing APIs (Stripe)	Coming Soon	🎯 Planned
Scheduling	Booking and availability management	Coming Soon	🎯 Planned

Core API Features

1. Standardized Response Pattern

Success Response:

{
  "success": true,
  "data": {
    "userId": "user_123",
    "profile": {
      "id": "profile_456", 
      "displayName": "John Doe"
    }
  },
  "message": "Profile retrieved successfully"
}

Error Response:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Builder profile not found",
    "statusCode": 404,
    "details": {
      "resourceId": "invalid_id"
    }
  }
}

Paginated Response:

{
  "success": true,
  "data": [
    { "id": "1", "name": "Builder 1" },
    { "id": "2", "name": "Builder 2" }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasMore": true
  }
}

2. Comprehensive Error Handling

All APIs use standardized error codes:

enum ApiErrorCode {
  BAD_REQUEST = 'bad_request',
  UNAUTHORIZED = 'unauthorized',
  FORBIDDEN = 'forbidden', 
  NOT_FOUND = 'not_found',
  VALIDATION_ERROR = 'validation_error',
  INTERNAL_ERROR = 'internal_error',
  CONFLICT = 'conflict',
  RATE_LIMITED = 'rate_limited'
}

→ Complete Error Handling Guide

3. Type Safety

All APIs provide full TypeScript interfaces with generic support:

// Client-side API function
async function getBuilderProfile(id: string): Promise<StandardApiResponse<BuilderProfileData>> {
  // Implementation with type safety
}

// Component usage with type checking
const response = await getBuilderProfile(id);
if (response.success && response.data) {
  // response.data is fully typed as BuilderProfileData
  console.log(response.data.displayName); // ✅ Type safe
}

4. Component Integration

Flattened response structures for seamless UI integration:

// Flattened profile response - no nested user object
{
  "userId": "user_123",
  "email": "[email protected]", 
  "displayName": "John Doe",
  "bio": "Builder bio",
  "avatarUrl": "https://...",
  "topSkills": ["React", "TypeScript"],
  "permissions": {
    "canEdit": true,
    "canDelete": false
  }
}

Quick Start Examples

1. Fetch Builder Profile

import { getBuilderProfileById } from '@/lib/profile/api';

async function loadProfile(id: string) {
  const response = await getBuilderProfileById(id);
  
  if (!response.success) {
    console.error('Error:', response.error?.message);
    return null;
  }
  
  return response.data; // Fully typed BuilderProfileData
}

2. Handle API Errors

import { useApiError } from '@/hooks/useApiError';

function MyComponent() {
  const { handleApiError } = useApiError();
  
  const loadData = async () => {
    const response = await fetchSomeData();
    
    if (!response.success) {
      handleApiError(response); // Automatic error handling & toasts
      return;
    }
    
    // Use response.data safely
  };
}

3. Server Component with Error Handling

import { getBuilderProfileBySlug } from '@/lib/profile/api';
import { notFound } from 'next/navigation';

export default async function BuilderPage({ params }: { params: { slug: string } }) {
  const response = await getBuilderProfileBySlug(params.slug);
  
  if (!response.success || !response.data) {
    notFound(); // Next.js 404 handling
  }
  
  const profile = response.data;
  
  return (
    <div>
      <h1>{profile.displayName}</h1>
      <p>{profile.bio}</p>
    </div>
  );
}

API Documentation

Core References

API Standardization Guide - Comprehensive standardization patterns
Error Handling Guide - Complete error codes and handling patterns
Profile API - User and builder profile management
Marketplace API - Builder discovery and marketplace

Implementation Guides

Migration from Legacy APIs - Convert existing endpoints
Testing Standardized APIs - Test patterns and examples
Component Integration - UI component patterns

Authentication

Most API endpoints require authentication. Authentication is handled via Clerk and integrated throughout the platform with automatic permission management.

Permission-Based Access

// Dynamic permissions in API responses
{
  "permissions": {
    "canView": true,
    "canEdit": false,    // Only owner or admin
    "canDelete": false,  // Only owner or admin  
    "canVerify": false   // Only admin
  }
}

Public vs Protected Endpoints

Public: Profile viewing, marketplace browsing
Protected: Profile editing, booking management, admin operations
Dynamic: Permissions calculated based on ownership and role

Performance & Reliability

Built-in Features

Error Monitoring: Automatic error reporting to Sentry
Structured Logging: Consistent logging across all endpoints
Performance Tracking: Request timing and metrics
Rate Limiting: Protection against abuse
Type Validation: Runtime validation with Zod schemas

Caching Strategy

Client-side: Intelligent caching of API responses
Server-side: Database query optimization
CDN: Static asset delivery optimization

Migration Path

The API standardization provides a clear migration path for existing endpoints:

✅ Completed: Marketplace APIs, Profile APIs
🔄 In Progress: Authentication APIs, Scheduling APIs
🎯 Planned: Payment APIs, Admin APIs

All new APIs automatically follow the standardized pattern, ensuring consistency across the entire platform.

​API Overview

​🎯 API Standardization

​API Organization

​Available APIs

​Core API Features

​1. Standardized Response Pattern

​2. Comprehensive Error Handling

​3. Type Safety

​4. Component Integration

​Quick Start Examples

​1. Fetch Builder Profile

​2. Handle API Errors

​3. Server Component with Error Handling

​API Documentation

​Core References

​Implementation Guides

​Authentication

​Permission-Based Access

​Public vs Protected Endpoints

​Performance & Reliability

​Built-in Features

​Caching Strategy

​Migration Path