Attendly Solutions

Posted on Oct 5

A Practical Guide to Integrating Third-Party REST APIs into Business Applications

#api #programming #tutorial

Introduction

Every modern business application relies on external services — payment processors, email providers, CRM platforms, shipping APIs, analytics dashboards. Integration is not optional; it is a fundamental requirement for building competitive software.

The difference between a working integration and a production-ready one often comes down to how carefully you consider the underlying design. This guide walks through the practical decisions that separate fragile, break-on-first-error code from robust, maintainable integrations.

Designing the API Client

Your first decision is architectural. Rather than scattering fetch() calls or axios.get() invocations throughout your codebase, encapsulate all external API interactions behind a dedicated client. This client becomes a single point of responsibility for:

Constructing URLs and query parameters
Serializing request bodies
Parsing responses
Handling errors

Interface Design

Define a clean interface that abstracts away the HTTP layer:

class PaymentApiClient {
  constructor(baseURL, apiKey) {
    this.baseURL = baseURL;
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async createCharge(amount, currency, customerId) {
    const response = await this.request('POST', '/charges', {
      amount,
      currency,
      customer: customerId
    });
    return response.data;
  }

  async getBalance() {
    const response = await this.request('GET', '/balance');
    return response.data;
  }
}

This abstraction means your business logic interacts with a simple method call — not raw HTTP requests. When the API provider changes their endpoint format or switches to GraphQL, you only update the client, not every call site.

Authentication Strategies

Authentication is the first security boundary for your integration. The strategy you choose depends on the API provider and the sensitivity of the data involved.

API Keys

The simplest approach — include a key in the Authorization header or as a query parameter. This works well for read-only operations or low-risk integrations. Never hardcode API keys in your source code. Use environment variables or a secrets manager:

const API_KEY = process.env.PAYMENT_API_KEY;
if (!API_KEY) {
  throw new Error('PAYMENT_API_KEY environment variable is required');
}

OAuth 2.0

For APIs that act on behalf of users (accessing their email, their records, their files), OAuth 2.0 is the standard. The flow involves:

Redirecting the user to the provider's authorization page
Receiving an authorization code via a callback
Exchanging the code for an access token and refresh token
Using the access token in subsequent requests

Key considerations:

Token storage: Store refresh tokens encrypted. Access tokens can be stored in memory.
Scope minimization: Request only the permissions your application actually needs.
Token lifecycle: Implement automatic refresh before tokens expire rather than waiting for 401 responses.

Mutual TLS

For high-security B2B integrations, mTLS adds a certificate-based layer of authentication. Both client and server validate each other's certificates. This is common in banking APIs and healthcare data exchanges.

Input Validation and Output Sanitization

Validation must happen at every boundary. The external API can return unexpected data, and your application should never trust raw responses.

Validating API Responses

function validateChargeResponse(data) {
  const requiredFields = ['id', 'status', 'amount', 'currency'];
  for (const field of requiredFields) {
    if (!data[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }

  if (typeof data.amount !== 'number' || data.amount ≤ 0) {
    throw new Error('Amount must be a positive number');
  }

  return data;
}

Validating User Input Before Sending

Never pass user input directly to the API. Validate and sanitize it first:

function normalizeEmail(email) {
  const normalized = email.trim().toLowerCase();
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)) {
    throw new InvalidInputError('Invalid email address');
  }
  return normalized;
}

This prevents bad data from corrupting external systems and provides consistent error messages to your users.

Retries and Timeouts

Network failures happen. Servers get overloaded. DNS lookups time out. Your integration must handle these gracefully.

Configuring Timeouts

const axiosInstance = axios.create({
  timeout: 5000,           // 5 seconds for initial connection
  headers: { 'X-Request-ID': generateUUID() }
});

Set timeouts short enough to fail fast but long enough to give the API a reasonable chance to respond. A 30-second timeout on an API call that normally takes 200ms is a recipe for cascading failures.

Retry Logic

Not all failures are retryable. GET requests and idempotent operations can be retried safely. POST requests that create resources should only be retried with a unique idempotency key:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt ≤ maxRetries; attempt++) {
    try {
      return await fetch(url, options);
    } catch (error) {
      if (attempt === maxRetries) throw error;

      // Only retry on transient errors
      if (error.code !== 'ECONNRESET' && error.code !== 'ETIMEDOUT') {
        throw error;
      }

      // Exponential backoff with jitter
      const backoff = Math.pow(2, attempt - 1) * 1000 + Math.random() * 500;
      await sleep(backoff);
    }
  }
}

The jitter (random component) prevents the "thundering herd" problem where many clients retry simultaneously and overwhelm the API.

Idempotency Keys

For non-GET operations, include an idempotency key provided by your application. This ensures that if a request times out and the client retries, the API processes the charge or creation exactly once:

const idempotencyKey = crypto.randomUUID();

await axios.post('/charges', chargeData, {
  headers: { 'Idempotency-Key': idempotencyKey }
});

Error Handling

A well-designed integration distinguishes between error types and responds appropriately.

Classifying Errors

class ApiError extends Error {
  constructor(statusCode, message, responseBody) {
    super(message);
    this.statusCode = statusCode;
    this.responseBody = responseBody;
  }
}

class AuthenticationError extends ApiError {
  constructor(message) {
    super(401, message, null);
  }
}

class RateLimitError extends ApiError {
  constructor(message, retryAfter) {
    super(429, message, null);
    this.retryAfter = retryAfter;
  }
}

Response Handling

async function request(method, path, body) {
  const response = await axios.request({ method, url: path, data: body });

  if (response.status ≥ 500) {
    throw new ServerError(`API returned ${response.status}`);
  }

  if (response.status === 429) {
    const retryAfter = response.headers['retry-after'] || 60;
    throw new RateLimitError('Rate limit exceeded', retryAfter);
  }

  if (response.status ≥ 400) {
    throw new ValidationError(response.data.message || 'Bad request');
  }

  return response;
}

User-Facing Errors

Map technical errors to user-friendly messages:

401 Unauthorized → "Your session has expired. Please sign in again."
403 Forbidden → "This action is not permitted in your region."
429 Rate Limited → "Too many requests. Please wait a moment and try again."
500 Server Error → "We're experiencing technical difficulties. Please try again shortly."

The end user should never see an HTTP status code or stack trace.

Logging and Observability

You cannot debug what you cannot observe. Logging for integrations requires more than just console.log.

Structured Logging

logger.info('API request started', {
  endpoint: '/charges',
  method: 'POST',
  requestId: reqId,
  userId: user.id
});

logger.error('API request failed', {
  endpoint: '/charges',
  statusCode: 502,
  error: error.message,
  requestId: reqId,
  duration: Date.now() - startTime
});

Structured logs include machine-readable fields alongside human-readable messages. This enables querying, alerting, and correlation across distributed systems.

What to Log (and What Not to Log)

Log:

Request endpoints and methods
Response status codes and durations
Error types and messages
Correlation/request IDs
User or tenant identifiers

Never log:

API keys or access tokens
Passwords or authentication credentials
PII (Personally Identifiable Information) such as full credit card numbers, SSNs, or addresses
Full request/response bodies containing sensitive data

Metrics

Track key integration metrics:

Request success/failure rates
Latency percentiles (p50, p95, p99)
Rate limit occurrences
Circuit breaker states
Retry counts

These metrics feed dashboards and alerting systems that catch problems before they reach users.

Testing API Integrations

Integration tests that hit real APIs are slow, fragile, and incur costs. Use a layered testing approach.

Unit Tests

Test your client class in isolation by mocking the HTTP layer:

describe('PaymentApiClient', () => {
  it('parses successful charge response', async () => {
    mockAxios.post.mockResolvedValue({
      data: { id: 'ch_123', status: 'succeeded', amount: 1000 }
    });

    const client = new PaymentApiClient('https://api.example.com', 'test_key');
    const result = await client.createCharge(1000, 'usd', 'cust_abc');

    expect(result.id).toBe('ch_123');
    expect(result.status).toBe('succeeded');
  });
});

Contract Tests

Verify that your application's expectations about the API contract match the actual API behavior. Tools like Pact allow you to define consumer-driven contracts and verify them against the provider.

Mock Servers for End-to-End Tests

Use a mock server (WireMock, Prism, or a custom nock setup) to simulate the real API for end-to-end tests. This gives you deterministic, fast tests that cover error paths:

mockServer
  .post('/charges')
  .reply(503, { error: 'service_unavailable' })
  .times(3);

// The client should retry and eventually fail
await expect(client.createCharge(1000, 'usd', 'cust_abc'))
  .rejects.toThrow(ServerError);

Integration Tests with Test Environments

Most API providers offer sandbox environments. Use them for integration tests that verify the full flow — authentication, request construction, response parsing — against a real API that won't charge real money.

Production Security Checklist

When your integration ships to production, verify these security considerations:

[ ] HTTPS only: All requests must use TLS. Reject certificates with invalid chains.
[ ] Secrets management: API keys and tokens stored in a vault, not in environment variables on disk.
[ ] Network segmentation: The integration service runs in a subnet with controlled egress rules.
[ ] Least privilege: Tokens have minimum required scopes. Separate tokens for read and write operations.
[ ] Request signing: For critical operations, sign requests with HMAC to detect tampering.
[ ] Audit logging: Every API call is logged with who initiated it, what data was accessed, and the result.
[ ] CORS configuration: If the API is called from browsers, restrict origins and methods.
[ ] Dependency security: Regularly scan the HTTP library and any related dependencies for vulnerabilities.

Conclusion

Building a reliable API integration is an exercise in defense in depth. You design a clean client, handle authentication carefully, validate every piece of data, implement thoughtful retry logic, classify and surface errors properly, log for observability without exposing secrets, test at every level, and lock down production security.

The effort upfront pays for itself in reduced production incidents, faster debugging, and a codebase that other developers can maintain with confidence.

DEV Community