API Integration Specialist

Expert guidance for integrating external APIs into applications with production-ready patterns, security best practices, and comprehensive error handling.

When to Use This Skill

Use this skill when:

• Integrating third-party APIs (Stripe, Twilio, SendGrid, etc.)

• Building API client libraries or wrappers

• Implementing OAuth 2.0, API keys, or JWT authentication

• Setting up webhooks and event-driven integrations

• Handling rate limits, retries, and circuit breakers

• Transforming API responses for application use

• Debugging API integration issues

Core Integration Principles

1. Authentication & Security

API Key Management:

// Store keys in environment variables, never in code const apiClient = new APIClient({ apiKey: process.env.SERVICE_API_KEY, baseURL: process.env.SERVICE_BASE_URL });

OAuth 2.0 Flow:

// Authorization Code Flow const oauth = new OAuth2Client({ clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET, redirectUri: process.env.REDIRECT_URI, scopes: ['read:users', 'write:data'] });

// Get authorization URL const authUrl = oauth.getAuthorizationUrl();

// Exchange code for tokens const tokens = await oauth.exchangeCode(code);

2. Request/Response Handling

Standardized Request Structure:

async function makeRequest(endpoint, options = {}) { const defaultHeaders = { 'Content-Type': 'application/json', 'Authorization': Bearer ${apiKey}, 'User-Agent': 'MyApp/1.0.0' };

const response = await fetch(${baseURL}${endpoint}, { ...options, headers: { ...defaultHeaders, ...options.headers } });

if (!response.ok) { throw new APIError(response.status, await response.json()); }

return response.json(); }

Response Transformation:

class APIClient { async getUser(userId) { const raw = await this.request(/users/${userId});

// Transform external API format to internal model
return {
  id: raw.user_id,
  email: raw.email_address,
  name: `${raw.first_name} ${raw.last_name}`,
  createdAt: new Date(raw.created_timestamp)
};

} }

3. Error Handling

Structured Error Types:

class APIError extends Error { constructor(status, body) { super(API Error: ${status}); this.status = status; this.body = body; this.isAPIError = true; }

isRateLimited() { return this.status === 429; }

isUnauthorized() { return this.status === 401; }

isServerError() { return this.status >= 500; } }

Retry Logic with Exponential Backoff:

async function retryWithBackoff(fn, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await fn(); } catch (error) { if (!error.isAPIError || !error.isServerError()) { throw error; // Don't retry client errors }

  if (i === maxRetries - 1) throw error;

  const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
  await sleep(delay);
}

} }

4. Rate Limiting

Client-Side Rate Limiter:

class RateLimiter { constructor(maxRequests, windowMs) { this.maxRequests = maxRequests; this.windowMs = windowMs; this.requests = []; }

async acquire() { const now = Date.now(); this.requests = this.requests.filter(t => now - t < this.windowMs);

if (this.requests.length >= this.maxRequests) {
  const oldestRequest = this.requests[0];
  const waitTime = this.windowMs - (now - oldestRequest);
  await sleep(waitTime);
  return this.acquire();
}

this.requests.push(now);

} }

const limiter = new RateLimiter(100, 60000); // 100 requests per minute

async function rateLimitedRequest(endpoint, options) { await limiter.acquire(); return makeRequest(endpoint, options); }

5. Webhook Handling

Webhook Verification:

function verifyWebhookSignature(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex');

return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); }

app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['stripe-signature'];

if (!verifyWebhookSignature(req.body, signature, process.env.STRIPE_WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); }

const event = JSON.parse(req.body); handleWebhookEvent(event);

res.status(200).send('Received'); });

Integration Patterns

REST API Client Pattern

class ServiceAPIClient { constructor(config) { this.apiKey = config.apiKey; this.baseURL = config.baseURL; this.timeout = config.timeout || 30000; }

async request(method, endpoint, data = null) { const options = { method, headers: { 'Authorization': Bearer ${this.apiKey}, 'Content-Type': 'application/json' }, timeout: this.timeout };

if (data) {
  options.body = JSON.stringify(data);
}

const response = await retryWithBackoff(() =>
  fetch(`${this.baseURL}${endpoint}`, options)
);

return response.json();

}

// Resource methods async getResource(id) { return this.request('GET', /resources/${id}); }

async createResource(data) { return this.request('POST', '/resources', data); }

async updateResource(id, data) { return this.request('PUT', /resources/${id}, data); }

async deleteResource(id) { return this.request('DELETE', /resources/${id}); } }

Pagination Handling

async function* fetchAllPages(endpoint, pageSize = 100) { let cursor = null;

do { const params = new URLSearchParams({ limit: pageSize, ...(cursor && { cursor }) });

const response = await apiClient.request('GET', `${endpoint}?${params}`);

yield response.data;

cursor = response.pagination?.next_cursor;

} while (cursor); }

// Usage for await (const page of fetchAllPages('/users')) { processUsers(page); }

Best Practices

Security

• Store API keys in environment variables or secrets management

• Use HTTPS for all API calls

• Verify webhook signatures

• Implement request signing for sensitive operations

• Rotate API keys regularly

Reliability

• Implement exponential backoff retry logic

• Handle rate limits gracefully

• Set appropriate timeouts

• Use circuit breakers for failing services

• Log all API interactions for debugging

Performance

• Cache responses when appropriate

• Batch requests when the API supports it

• Use streaming for large responses

• Implement connection pooling

• Monitor API usage and costs

Monitoring

• Track API response times

• Alert on error rate increases

• Monitor rate limit consumption

• Log failed requests with context

• Set up health checks for critical integrations

Common Integration Examples

Stripe Payment Processing

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

async function createPaymentIntent(amount, currency = 'usd') { return await stripe.paymentIntents.create({ amount, currency, automatic_payment_methods: { enabled: true } }); }

SendGrid Email Sending

const sgMail = require('@sendgrid/mail'); sgMail.setApiKey(process.env.SENDGRID_API_KEY);

async function sendEmail(to, subject, html) { await sgMail.send({ to, from: process.env.FROM_EMAIL, subject, html }); }

Twilio SMS

const twilio = require('twilio')( process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN );

async function sendSMS(to, body) { await twilio.messages.create({ to, from: process.env.TWILIO_PHONE_NUMBER, body }); }

Troubleshooting

Authentication Issues

• Verify API keys are correctly set

• Check token expiration

• Ensure proper OAuth scopes

• Validate signature generation

Rate Limiting

• Implement client-side rate limiting

• Use batch endpoints when available

• Spread requests over time

• Consider upgrading API tier

Timeout Errors

• Increase timeout values for slow endpoints

• Implement request cancellation

• Use streaming for large payloads

• Check network connectivity

When integrating APIs, prioritize security, reliability, and maintainability. Always test error scenarios and edge cases before production deployment.