Integration Patterns

Common patterns for integrating Zaits API into your application architecture.

Authentication Patterns

API Key Authentication

Simple and direct API authentication using API keys.

When to use:

  • Server-to-server integrations

  • Backend services

  • Microservices communication

Example:

const response = await fetch('https://api.zaits.net/v1/face/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

Session-Based Authentication

Combine API key with user sessions for web applications.

When to use:

  • Web applications with user accounts

  • Multi-tenant applications

  • Applications requiring per-user API usage tracking

Flow:

  1. User logs in to your application

  2. Backend creates session and stores user context

  3. Backend makes Zaits API calls on behalf of user

  4. Results returned to user through your application

Error Handling Patterns

Retry with Exponential Backoff

Handle transient failures with automatic retries.

Example:

async function callWithRetry(apiCall, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiCall();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (!isRetryable(error)) throw error;

      // Wait with exponential backoff
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

function isRetryable(error) {
  return error.status === 429 || // Rate limit
         error.status === 503 || // Service unavailable
         error.status >= 500;    // Server errors
}

Circuit Breaker Pattern

Prevent cascading failures by temporarily disabling failing services.

When to use:

  • High-availability applications

  • Systems with multiple dependent services

  • Applications requiring graceful degradation

Asynchronous Processing

Background Job Processing

Process API requests asynchronously using job queues.

When to use:

  • Long-running operations

  • Batch processing

  • High-volume processing

Flow:

  1. User uploads file

  2. Create background job and return job ID

  3. Process asynchronously using queue (Celery, Bull, etc.)

  4. Store results in database

  5. Notify user via webhook or polling

Webhook Integration

Receive real-time notifications for events.

When to use:

  • Real-time event processing

  • Document signing workflows

  • Verification completion notifications

Implementation:

  1. Configure webhook URL in Zaits dashboard

  2. Implement webhook endpoint in your application

  3. Verify webhook signatures for security

  4. Process events asynchronously

Caching Strategies

Result Caching

Cache API responses to reduce costs and improve performance.

When to cache:

  • Document verification results (short TTL)

  • Face analysis results for known images

  • OCR results for static documents

When NOT to cache:

  • Real-time verification requests

  • Liveness detection

  • Time-sensitive validations

Example:

const cacheKey = `face_verify:${imageHash1}:${imageHash2}`;
let result = await cache.get(cacheKey);

if (!result) {
  result = await zaitsApi.faceVerify(image1, image2);
  await cache.set(cacheKey, result, 3600); // Cache for 1 hour
}

Scaling Patterns

Load Balancing

Distribute API requests across multiple application instances.

Components:

  • Load balancer (nginx, AWS ALB, etc.)

  • Multiple application servers

  • Shared cache (Redis)

  • Centralized logging

Rate Limit Management

Manage API rate limits across distributed systems.

Strategies:

  • Use distributed rate limiting (Redis)

  • Implement request queuing

  • Priority-based processing

  • Fallback to cached results when limit reached

Security Patterns

Request Validation

Validate all inputs before making API calls.

Validations:

  • File type and size

  • Image dimensions

  • Required fields

  • User permissions

Secure File Handling

Safely handle uploaded files.

Best practices:

  • Validate file types

  • Scan for malware

  • Use temporary storage

  • Clean up after processing

  • Don't expose file paths

Monitoring Patterns

API Usage Tracking

Monitor your API usage to optimize costs.

Track:

  • Request volume per endpoint

  • Success/error rates

  • Response times

  • Cost per operation

Error Logging

Log errors for debugging and monitoring.

Log:

  • Request parameters (without sensitive data)

  • Error messages and stack traces

  • User context

  • Timestamp and request ID

Multi-Tenancy Patterns

Tenant Isolation

Isolate data and resources per tenant.

Implementation:

  • One API key per tenant, or

  • Backend proxy with tenant identification

  • Separate databases/schemas per tenant

  • Tenant-specific rate limits

Integration Checklist

Before deploying to production:

Getting Started

For more details, see:

PreviouscURL Examples

Last updated