Development Guides

API Key Security

Your API keys are sensitive credentials that should be protected at all times. Never expose them in client-side code or commit them to version control.

// ❌ Don't do this
const apiKey = "oag_live_1234567890abcdef";

// ✅ Do this instead
const apiKey = process.env.OAG_API_KEY;

Rate Limiting

Our API implements rate limiting to ensure fair usage and maintain service quality for all users. Understanding and respecting these limits is crucial for building reliable applications.

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff to handle these gracefully.

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      await sleep(retryAfter * 1000 || Math.pow(2, i) * 1000);
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Error Handling

Proper error handling ensures your application can gracefully recover from failures and provide meaningful feedback to users.

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your account. Configure webhook endpoints to stay synchronized with our platform.

Setting Up Webhooks

1. 1

   Navigate to the Webhooks section in your dashboard

2. 2

   Add your endpoint URL (must be HTTPS in production)

3. 3

   Select the events you want to receive

4. 4

   Save your webhook secret for signature verification

// Verify webhook signature
import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Versioning

We version our API to ensure backward compatibility and give you time to migrate when we introduce breaking changes.

curl https://api.oag.com/v2/flights \
  -H "Authorization: Bearer oag_live_..." \
  -H "OAG-Version: 2024-04"

Always specify the API version in your requests. If no version is specified, we'll use the latest version, which may introduce breaking changes.