veza/docs/archive/backend-sessions-2026/API_FRONTEND_GUIDE.md

Veza API Frontend Integration Guide

1. Introduction

This guide provides instructions for consuming the Veza Backend API in frontend applications (React, Vue, etc.).

2. API Client Setup

We recommend creating a typed API client.

2.1. TypeScript Interfaces

// Base Response Envelope
export interface APIResponse<T> {
  success: boolean;
  data: T | null;
  error: APIError | null;
}

// Error Structure
export interface APIError {
  code: number;
  message: string;
  details?: ValidationErrorDetail[] | null;
  request_id?: string;
  timestamp?: string;
}

export interface ValidationErrorDetail {
  field: string;
  message: string;
  value?: string;
  tag?: string;
}

// Pagination
export interface PaginatedList<T> {
  list: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    has_next: boolean;
  };
}

3. Making Requests

3.1. Fetch Wrapper Example

async function apiRequest<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const token = localStorage.getItem('access_token');
  const headers = {
    'Content-Type': 'application/json',
    ...(token ? { 'Authorization': `Bearer ${token}` } : {}),
    ...options.headers,
  };

  const response = await fetch(\`/api/v1${endpoint}\`, { ...options, headers });
  const result: APIResponse<T> = await response.json();

  if (!result.success) {
    // Handle API Error
    console.error('API Error:', result.error);
    throw new Error(result.error?.message || 'Unknown API Error');
  }

  // Return the data payload directly
  return result.data as T;
}

4. Handling Validation Errors

When a 400 Bad Request or 422 Unprocessable Entity occurs:

try {
  await apiRequest('/auth/login', { method: 'POST', body: JSON.stringify(creds) });
} catch (error) {
  // If error has details, map them to form fields
  const apiError = error as APIError; // You might need to adjust error throwing logic
  if (apiError.details) {
    apiError.details.forEach(detail => {
      setFieldError(detail.field, detail.message);
    });
  }
}

5. Resources & Endpoints (Swagger)

For a full list of endpoints, request/response bodies, please refer to the OpenAPI Specification:

• Local URL: http://localhost:8080/swagger/index.html
• File: docs/swagger.json