adaptationio/api-client

API Client Builder

Overview

Build robust REST API clients with authentication, comprehensive error handling, automatic retries, and request/response management.

Quick Start

Basic API Client

const client = new APIClient({
  baseURL: 'https://api.example.com',
  apiKey: process.env.API_KEY
});

const response = await client.get('/users');
console.log(response.data);

Features

• ✓ Multiple authentication methods (API key, OAuth, JWT)
• ✓ Automatic retry with exponential backoff
• ✓ Request/response logging
• ✓ Error classification and handling
• ✓ Rate limiting support
• ✓ Request timeout configuration

Workflow

Step 1: Configure Client

Create client with base configuration:

const client = new APIClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  retries: 3
});

Step 2: Add Authentication

See references/authentication-guide.md for all methods.

API Key:

client.setAuth({
  type: 'apiKey',
  key: process.env.API_KEY
});

OAuth 2.0:

client.setAuth({
  type: 'oauth',
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET
});

Step 3: Make Requests

// GET request
const users = await client.get('/users');

// POST request
const newUser = await client.post('/users', {
  name: 'John Doe',
  email: '[email protected]'
});

// PUT request
const updated = await client.put('/users/123', {
  name: 'Jane Doe'
});

// DELETE request
await client.delete('/users/123');

Step 4: Handle Errors

try {
  const response = await client.get('/users');
  console.log(response.data);
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Request failed:', error.message);
  }
}

Configuration

Complete Configuration Options

const client = new APIClient({
  // Base configuration
  baseURL: 'https://api.example.com',
  timeout: 5000,                  // Request timeout (ms)

  // Retry configuration
  retries: 3,                     // Number of retries
  retryDelay: 1000,               // Initial retry delay (ms)
  retryMult iplier: 2,              // Exponential backoff multiplier

  // Authentication (see references/authentication-guide.md)
  auth: {
    type: 'apiKey',
    key: process.env.API_KEY
  },

  // Headers
  headers: {
    'Content-Type': 'application/json',
    'Custom-Header': 'value'
  },

  // Logging
  logging: true,                  // Enable request/response logging
  logLevel: 'info'               // debug, info, warn, error
});

See templates/api-config-template.json for complete configuration template.

Authentication Methods

Method 1: API Key

client.setAuth({
  type: 'apiKey',
  key: process.env.API_KEY,
  header: 'X-API-Key'  // Optional, default: 'Authorization'
});

Method 2: OAuth 2.0

See references/authentication-guide.md#oauth for complete OAuth flow.

Method 3: JWT

See references/authentication-guide.md#jwt for JWT implementation.

Error Handling

Error Classification

Errors are classified into categories for appropriate handling:

| Status Code | Category | Retry? | Action | |-------------|----------|--------|--------| | 400 | Client Error | No | Fix request | | 401 | Auth Error | No | Refresh token | | 403 | Permission | No | Check permissions | | 404 | Not Found | No | Check endpoint | | 429 | Rate Limit | Yes | Wait and retry | | 500 | Server Error | Yes | Retry | | 503 | Unavailable | Yes | Retry |

See references/error-handling.md for complete error handling strategies.

Validation

Validate API configuration before using:

python scripts/validate-config.py config.json

Templates

Copy templates from templates/ directory:

• api-config-template.json - Complete configuration
• error-handler-template.js - Error handling code
• retry-logic-template.js - Retry implementation

References

• Authentication Guide - All auth methods
• Error Handling - Comprehensive error strategies
• Rate Limiting - Handle rate limits
• Testing - Test API clients

---

Version: 1.0 Last Updated: October 25, 2025 Example Type: Complex skill (full structure)