# 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

```typescript
// 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

```typescript
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:

```typescript
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`