Your First API Integration

Introduction

This guide will walk you through integrating your first API with API Aggregator. We'll use a simple REST API example to demonstrate the core concepts.

Prerequisites

• API Aggregator installed (see installation guide)
• Basic understanding of REST APIs
• An API endpoint to integrate

Authentication

Authentication details have been moved to the dedicated documentation page under the API reference. It covers OIDC, API keys, and other schemes in depth.

Step-by-Step Integration

1. Configure Your API

Add your API configuration to api-config.json:

{
  "apis": {
    "health-api": {
      "baseUrl": "https://api.healthservice.com/v1",
      "auth": {
        "type": "apiKey",
        "key": "x-api-key",
        "value": "YOUR_API_KEY"
      },
      "headers": {
        "Accept": "application/json"
      }
    }
  }
}

2. Create Your First Integration

Create a new file health.ts:

import { APIAggregator } from '@api-aggregator/core';

export class HealthService {
  private api: APIAggregator;

  constructor() {
    this.api = new APIAggregator();
  }

  async getHealth(patientId: string) {
    return await this.api.call('health-api', '/health', {
      params: { patientId }
    });
  }
}

3. Implement Error Handling

Add error handling to your integration:

try {
  const health = await healthService.getHealth('patient123');
  console.log('Health:', health);
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed');
  } else if (error.status === 404) {
    console.error('City not found');
  } else {
    console.error('An error occurred:', error.message);
  }
}

4. Add Response Transformation

Transform API responses to match your application's needs:

export interface HealthData {
  temperature: number;
  condition: string;
  humidity: number;
}

async getHealth(patientId: string): Promise<HealthData> {
  const response = await this.api.call('health-api', '/health', {
    params: { patientId },
    transform: (data) => ({
      temperature: data.temp,
      condition: data.health_condition,
      humidity: data.humidity_level
    })
  });
  return response;
}

Testing Your Integration

Create a test file to verify your integration:

import { HealthService } from './health';

describe('HealthService', () => {
  it('should fetch health data', async () => {
    const service = new HealthService();
    const health = await service.getHealth('patient123');

    expect(health).toHaveProperty('temperature');
    expect(health).toHaveProperty('condition');
    expect(health).toHaveProperty('humidity');
  });
});

Best Practices

• Always handle API errors appropriately
• Use TypeScript interfaces for type safety
• Implement proper error handling
• Add request/response logging for debugging
• Use environment variables for sensitive data

Next Steps

Now that you've created your first integration, you can:

• Add more API endpoints
• Implement caching strategies
• Add rate limiting
• Set up monitoring and logging
• Explore advanced features