Integrating Real-Time Aviation APIs in a Mission-Critical Platform
How we integrated multiple real-time aviation APIs for flight tracking, weather data, and NOTAMs into a mission-critical platform with circuit breakers, caching, and graceful degradation.
Tags
Integrating Real-Time Aviation APIs in a Mission-Critical Platform
TL;DR
Circuit breakers and multi-layer caching across aviation API providers achieved high data availability for a mission-critical flight operations platform, even when individual providers experienced outages. The integration layer used Apollo Client for GraphQL caching, Sabre REST APIs for booking and scheduling operations, a normalization layer that unified disparate API response formats, and graceful degradation patterns that kept the platform operational when upstream services failed.
The Challenge
I was building a flight operations platform that integrated with Sabre's REST and GraphQL APIs for real-time aviation service workflows: booking management, flight scheduling, fare quoting, and passenger service operations. This was not a consumer travel app. It was an operational tool used by airline staff and travel operations teams where incorrect or stale data had real consequences, from double-booked flights to missed operational windows.
The challenges were specific to aviation API integration:
- ›Sabre APIs have complex authentication flows with token lifecycle management across multiple environments (cert, production)
- ›Response formats varied significantly between REST and GraphQL endpoints, even for conceptually similar data
- ›Rate limits were strict, and exceeding them during peak operations could lock out the entire platform
- ›Data freshness requirements varied by domain: flight status needed near-real-time updates, fare data could tolerate minutes of staleness, and booking records needed to be authoritative on every read
- ›Upstream outages were not hypothetical. Third-party aviation APIs experience maintenance windows, degraded performance, and occasional failures that the platform needed to handle without going down
I designed the integration layer, caching strategy, and error handling architecture for this platform.
The Architecture
API Client Layer
The foundation was a typed API client that handled authentication, rate limiting, and request/response normalization for both Sabre REST and GraphQL endpoints.
// sabre-client.ts
interface SabreConfig {
environment: 'cert' | 'production';
clientId: string;
clientSecret: string;
pcc: string; // Pseudo City Code
rateLimits: {
requestsPerSecond: number;
burstLimit: number;
};
}
class SabreApiClient {
private tokenManager: TokenManager;
private rateLimiter: RateLimiter;
private circuitBreaker: CircuitBreaker;
constructor(private config: SabreConfig) {
this.tokenManager = new TokenManager(config);
this.rateLimiter = new RateLimiter(
config.rateLimits.requestsPerSecond,
config.rateLimits.burstLimit
);
this.circuitBreaker = new CircuitBreaker({
failureThreshold: 5,
resetTimeout: 30_000, // 30 seconds in open state
halfOpenRequests: 2, // test requests before fully closing
});
}
async restRequest<T>(
endpoint: string,
options: RequestOptions
): Promise<ApiResponse<T>> {
// Circuit breaker check
if (this.circuitBreaker.isOpen()) {
throw new CircuitOpenError(
`Circuit open for Sabre REST. Last failure: ${this.circuitBreaker.lastFailureReason}`
);
}
// Rate limiting — queues request if at limit
await this.rateLimiter.acquire();
// Token management — handles refresh transparently
const token = await this.tokenManager.getValidToken();
try {
const response = await fetch(
`${this.getBaseUrl()}${endpoint}`,
{
...options,
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
...options.headers,
},
signal: AbortSignal.timeout(options.timeout ?? 10_000),
}
);
if (!response.ok) {
const error = await this.parseError(response);
this.circuitBreaker.recordFailure(error.message);
throw error;
}
this.circuitBreaker.recordSuccess();
const data = await response.json();
return { data: data as T, headers: response.headers };
} catch (error) {
if (error instanceof CircuitOpenError) throw error;
this.circuitBreaker.recordFailure(
error instanceof Error ? error.message : 'Unknown error'
);
throw error;
}
}
private getBaseUrl(): string {
return this.config.environment === 'production'
? 'https://api.sabre.com'
: 'https://api-crt.cert.sabre.com';
}
}Token Lifecycle Management
Sabre API tokens have expiration times and require careful lifecycle management. The token manager handled initial authentication, proactive refresh before expiry, and retry logic for failed token requests.
// token-manager.ts
class TokenManager {
private currentToken: string | null = null;
private tokenExpiry: number = 0;
private refreshPromise: Promise<string> | null = null;
constructor(private config: SabreConfig) {}
async getValidToken(): Promise<string> {
// If token is valid and not expiring soon, return it
const now = Date.now();
const bufferMs = 60_000; // refresh 1 minute before expiry
if (this.currentToken && this.tokenExpiry > now + bufferMs) {
return this.currentToken;
}
// If a refresh is already in progress, wait for it
// This prevents multiple concurrent refresh requests
if (this.refreshPromise) {
return this.refreshPromise;
}
// Initiate token refresh
this.refreshPromise = this.refreshToken();
try {
const token = await this.refreshPromise;
return token;
} finally {
this.refreshPromise = null;
}
}
private async refreshToken(): Promise<string> {
const credentials = Buffer.from(
`${this.config.clientId}:${this.config.clientSecret}`
).toString('base64');
const response = await fetch(
`${this.getAuthUrl()}/v2/auth/token`,
{
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: 'grant_type=client_credentials',
signal: AbortSignal.timeout(5_000),
}
);
if (!response.ok) {
throw new AuthenticationError(
`Token refresh failed: ${response.status} ${response.statusText}`
);
}
const tokenData = await response.json();
this.currentToken = tokenData.access_token;
this.tokenExpiry = Date.now() + (tokenData.expires_in * 1000);
return this.currentToken;
}
}The critical detail is the refreshPromise deduplication. When multiple API calls happen concurrently and the token is expired, all of them would independently try to refresh the token, creating a burst of authentication requests. By storing the in-flight refresh promise, subsequent callers join the existing refresh instead of creating new ones.
Apollo Client Caching Strategy
For GraphQL endpoints, Apollo Client's normalized cache was central to keeping data fresh while minimizing API calls. The caching strategy varied by data domain.
// apollo-config.ts
import {
ApolloClient,
InMemoryCache,
HttpLink,
ApolloLink,
} from '@apollo/client';
import { RetryLink } from '@apollo/client/link/retry';
const cache = new InMemoryCache({
typePolicies: {
FlightSchedule: {
keyFields: ['flightNumber', 'departureDate'],
fields: {
// Merge incoming schedule updates with cached data
segments: {
merge(existing = [], incoming) {
return incoming; // always prefer latest schedule
},
},
},
},
FareQuote: {
keyFields: ['quoteId'],
fields: {
// Fares expire — mark stale after TTL
expiresAt: {
read(existing) {
return existing;
},
},
},
},
BookingRecord: {
keyFields: ['pnr'],
// Booking records should never be served from stale cache
// Always fetch from network
},
},
});
// Custom link for cache TTL enforcement
const cacheControlLink = new ApolloLink((operation, forward) => {
return forward(operation).map(response => {
const context = operation.getContext();
const maxAge = context.cacheMaxAge;
if (maxAge) {
// Store cache timestamp for TTL checks
const cacheKey = operation.operationName;
cacheTimestamps.set(cacheKey, {
storedAt: Date.now(),
maxAge,
});
}
return response;
});
});
const retryLink = new RetryLink({
delay: {
initial: 500,
max: 5000,
jitter: true, // randomize to prevent thundering herd
},
attempts: {
max: 3,
retryIf: (error) => {
// Retry on network errors and 5xx, not on 4xx
if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
return false;
}
return true;
},
},
});
export const apolloClient = new ApolloClient({
cache,
link: ApolloLink.from([
cacheControlLink,
retryLink,
new HttpLink({ uri: '/graphql' }),
]),
defaultOptions: {
watchQuery: {
// Default to cache-first, override per query as needed
fetchPolicy: 'cache-first',
nextFetchPolicy: 'cache-and-network',
},
},
});The fetch policies were domain-specific:
// Flight status — needs near-real-time data
const { data: flightStatus } = useQuery(GET_FLIGHT_STATUS, {
variables: { flightNumber, date },
fetchPolicy: 'network-only', // always fetch fresh
pollInterval: 15_000, // poll every 15 seconds
context: { cacheMaxAge: 15_000 },
});
// Fare quotes — can tolerate short staleness, expensive to fetch
const { data: fareQuote } = useQuery(GET_FARE_QUOTE, {
variables: { origin, destination, date, passengers },
fetchPolicy: 'cache-first',
context: { cacheMaxAge: 300_000 }, // 5 minutes
});
// Booking record — must be authoritative, never serve stale
const { data: booking } = useQuery(GET_BOOKING, {
variables: { pnr },
fetchPolicy: 'no-cache', // never cache PNR data
});Circuit Breaker Implementation
The circuit breaker pattern was essential for mission-critical operations. When an upstream API started failing, the circuit breaker prevented the platform from hammering a degraded service and allowed graceful degradation.
// circuit-breaker.ts
type CircuitState = 'closed' | 'open' | 'half-open';
interface CircuitBreakerConfig {
failureThreshold: number; // failures before opening
resetTimeout: number; // ms before trying half-open
halfOpenRequests: number; // test requests in half-open
}
class CircuitBreaker {
private state: CircuitState = 'closed';
private failureCount: number = 0;
private lastFailureTime: number = 0;
private halfOpenSuccesses: number = 0;
public lastFailureReason: string = '';
constructor(private config: CircuitBreakerConfig) {}
isOpen(): boolean {
if (this.state === 'closed') return false;
if (this.state === 'open') {
// Check if reset timeout has elapsed
const elapsed = Date.now() - this.lastFailureTime;
if (elapsed >= this.config.resetTimeout) {
this.state = 'half-open';
this.halfOpenSuccesses = 0;
return false; // allow test requests
}
return true; // still in cooldown
}
// half-open: allow limited requests
return false;
}
recordSuccess(): void {
if (this.state === 'half-open') {
this.halfOpenSuccesses++;
if (this.halfOpenSuccesses >= this.config.halfOpenRequests) {
// Enough successful test requests — close the circuit
this.state = 'closed';
this.failureCount = 0;
}
} else {
this.failureCount = 0;
}
}
recordFailure(reason: string): void {
this.failureCount++;
this.lastFailureTime = Date.now();
this.lastFailureReason = reason;
if (this.state === 'half-open') {
// Failed during test — reopen
this.state = 'open';
} else if (this.failureCount >= this.config.failureThreshold) {
this.state = 'open';
}
}
getState(): { state: CircuitState; failureCount: number } {
return { state: this.state, failureCount: this.failureCount };
}
}Graceful Degradation Patterns
When the circuit breaker opened or an API call failed after retries, the platform did not show an error page. Instead, it degraded gracefully based on the data domain:
// degradation-handler.ts
class GracefulDegradation {
async getFlightStatus(
flightNumber: string,
date: string
): Promise<FlightStatusResponse> {
try {
// Primary: Sabre real-time API
return await this.sabreClient.getFlightStatus(flightNumber, date);
} catch (error) {
if (error instanceof CircuitOpenError) {
// Fallback 1: serve from Redis cache with stale indicator
const cached = await this.redis.get(`flight:${flightNumber}:${date}`);
if (cached) {
const parsed = JSON.parse(cached);
return {
...parsed,
dataFreshness: 'stale',
lastUpdated: parsed._cachedAt,
warning: 'Real-time data temporarily unavailable. Showing last known status.',
};
}
}
// Fallback 2: return minimal known information
return {
flightNumber,
date,
status: 'UNKNOWN',
dataFreshness: 'unavailable',
warning: 'Flight status data is temporarily unavailable. Please verify through alternate channels.',
};
}
}
async getFareQuote(
params: FareQuoteParams
): Promise<FareQuoteResponse> {
try {
return await this.sabreClient.getFareQuote(params);
} catch (error) {
// Fare quotes cannot be served stale — prices may have changed
// Return an explicit unavailability response, not a stale price
return {
available: false,
reason: 'Fare pricing service is temporarily unavailable.',
retryAfter: this.getCircuitResetTime(),
suggestion: 'Cached fare estimates are not shown to prevent quoting incorrect prices.',
};
}
}
}The degradation strategy was intentionally different per domain. Flight status could be served stale with a warning because a slightly outdated departure time is better than no information. Fare quotes could not be served stale because showing an incorrect price could lead to booking errors with financial consequences. The platform made this distinction explicit to operators through visual indicators.
Data Normalization Layer
Sabre REST and GraphQL responses had different structures for conceptually similar data. The normalization layer converted everything into a unified internal schema:
// normalizers.ts
interface NormalizedFlight {
flightNumber: string;
airline: { code: string; name: string };
departure: {
airport: { code: string; name: string; terminal?: string; gate?: string };
scheduled: string; // ISO 8601
estimated?: string;
actual?: string;
};
arrival: {
airport: { code: string; name: string; terminal?: string; gate?: string };
scheduled: string;
estimated?: string;
actual?: string;
};
status: FlightStatus;
aircraft?: { type: string; registration?: string };
}
// Sabre REST response normalization
function normalizeRestFlightStatus(raw: SabreRestFlightResponse): NormalizedFlight {
const segment = raw.OTA_AirDetailsRS.FlightDetails.FlightLegDetails;
return {
flightNumber: `${segment.MarketingCarrier}${segment.FlightNumber}`,
airline: {
code: segment.MarketingCarrier,
name: segment.MarketingCarrierName ?? segment.MarketingCarrier,
},
departure: {
airport: {
code: segment.DepartureAirport,
name: segment.DepartureAirportName ?? segment.DepartureAirport,
terminal: segment.DepartureTerminal ?? undefined,
gate: segment.DepartureGate ?? undefined,
},
scheduled: segment.ScheduledDepartureDateTime,
estimated: segment.EstimatedDepartureDateTime ?? undefined,
actual: segment.ActualDepartureDateTime ?? undefined,
},
arrival: {
airport: {
code: segment.ArrivalAirport,
name: segment.ArrivalAirportName ?? segment.ArrivalAirport,
terminal: segment.ArrivalTerminal ?? undefined,
gate: segment.ArrivalGate ?? undefined,
},
scheduled: segment.ScheduledArrivalDateTime,
estimated: segment.EstimatedArrivalDateTime ?? undefined,
actual: segment.ActualArrivalDateTime ?? undefined,
},
status: mapSabreStatus(segment.FlightStatus),
aircraft: segment.EquipmentType
? { type: segment.EquipmentType, registration: segment.TailNumber }
: undefined,
};
}
// Sabre GraphQL response normalization
function normalizeGraphQLFlightStatus(
raw: SabreGraphQLFlightNode
): NormalizedFlight {
return {
flightNumber: raw.flightDesignator,
airline: {
code: raw.operatingCarrier.code,
name: raw.operatingCarrier.name,
},
departure: {
airport: {
code: raw.origin.iataCode,
name: raw.origin.name,
terminal: raw.origin.terminal ?? undefined,
gate: raw.departureGate ?? undefined,
},
scheduled: raw.scheduledDeparture,
estimated: raw.estimatedDeparture ?? undefined,
actual: raw.actualDeparture ?? undefined,
},
arrival: {
airport: {
code: raw.destination.iataCode,
name: raw.destination.name,
terminal: raw.destination.terminal ?? undefined,
gate: raw.arrivalGate ?? undefined,
},
scheduled: raw.scheduledArrival,
estimated: raw.estimatedArrival ?? undefined,
actual: raw.actualArrival ?? undefined,
},
status: mapGraphQLStatus(raw.status),
aircraft: raw.aircraft
? { type: raw.aircraft.typeCode, registration: raw.aircraft.registration }
: undefined,
};
}This normalization meant the rest of the application worked with a single, consistent NormalizedFlight type regardless of whether the data came from a REST or GraphQL endpoint. When Sabre updated their API response structure (which happened), only the normalization function needed to change, not every component that consumed flight data.
Real-Time Data Freshness Indicators
For mission-critical operations, operators needed to know how fresh their data was. We implemented a data freshness system that visually communicated staleness:
// DataFreshnessIndicator.tsx
interface FreshnessConfig {
freshThreshold: number; // ms — data is "fresh"
warningThreshold: number; // ms — data is "aging"
staleThreshold: number; // ms — data is "stale"
}
const FRESHNESS_CONFIGS: Record<string, FreshnessConfig> = {
flightStatus: {
freshThreshold: 15_000, // fresh under 15s
warningThreshold: 60_000, // warning 15s-60s
staleThreshold: 120_000, // stale after 2 min
},
fareQuote: {
freshThreshold: 300_000, // fresh under 5 min
warningThreshold: 600_000, // warning 5-10 min
staleThreshold: 900_000, // stale after 15 min
},
};
function DataFreshnessIndicator({
dataType,
lastUpdated,
}: {
dataType: string;
lastUpdated: Date;
}) {
const [freshness, setFreshness] = useState<'fresh' | 'warning' | 'stale'>('fresh');
const config = FRESHNESS_CONFIGS[dataType];
useEffect(() => {
const interval = setInterval(() => {
const age = Date.now() - lastUpdated.getTime();
if (age < config.freshThreshold) {
setFreshness('fresh');
} else if (age < config.staleThreshold) {
setFreshness('warning');
} else {
setFreshness('stale');
}
}, 5_000); // check every 5 seconds
return () => clearInterval(interval);
}, [lastUpdated, config]);
const labels = {
fresh: 'Live',
warning: `Updated ${formatRelativeTime(lastUpdated)}`,
stale: `Stale — last update ${formatRelativeTime(lastUpdated)}`,
};
return (
<span
className={cn(
'inline-flex items-center gap-1.5 text-sm',
freshness === 'fresh' && 'text-green-600',
freshness === 'warning' && 'text-amber-600',
freshness === 'stale' && 'text-red-600'
)}
role="status"
aria-live="polite"
>
<span className={cn(
'h-2 w-2 rounded-full',
freshness === 'fresh' && 'bg-green-500 animate-pulse',
freshness === 'warning' && 'bg-amber-500',
freshness === 'stale' && 'bg-red-500'
)} />
{labels[freshness]}
</span>
);
}The aria-live="polite" attribute ensured screen readers announced freshness changes, which was important for accessibility in an operations environment where operators might monitor multiple screens.
Key Decisions & Trade-offs
Apollo Client vs. React Query for data fetching. Apollo Client was chosen because we had GraphQL endpoints where the normalized cache and automatic cache updates provided significant value. For REST-only integrations, React Query would have been simpler. The trade-off was Apollo's larger bundle size and the learning curve of its cache normalization model.
Polling vs. WebSocket for real-time updates. Sabre APIs do not offer WebSocket connections, so polling was the only option for upstream data. On the frontend, we used WebSocket connections between our server and the client to push updates without polling. The server polled Sabre at configured intervals and pushed changes through WebSockets only when data actually changed, reducing unnecessary renders.
Per-domain circuit breakers vs. a single global circuit breaker. We used per-domain circuit breakers (separate for flight status, fare quotes, bookings) because a failure in fare quoting should not block flight status lookups. The trade-off was more configuration surface area and more state to monitor, but the isolation was worth it for a mission-critical platform.
Stale data with warnings vs. no data. For flight status, we chose to show stale data with visual warnings rather than showing nothing. For fare quotes, we chose to show nothing rather than stale prices. This distinction was controversial with stakeholders who wanted consistent behavior. The domain-specific approach was the right call because the consequences of stale data differed dramatically between domains.
Results & Outcomes
The integration layer provided reliable data availability even during individual API provider degradation events. Circuit breakers prevented cascading failures, and the multi-layer caching strategy reduced API call volume while maintaining data freshness where it mattered.
The normalization layer paid dividends immediately. When Sabre updated their response schemas (which happened across several API versions during the project), the changes were contained to the normalization functions. No UI components needed modification.
Operators reported confidence in the data freshness indicators. The visual distinction between live, aging, and stale data helped them make operational decisions with appropriate caution. The "stale" indicator prompted operators to verify through alternate channels rather than acting on potentially outdated information.
Rate limit compliance improved through the centralized rate limiter. Before the integration layer, individual API calls were made without coordination, occasionally triggering rate limit lockouts during peak operations. The queuing rate limiter prevented this entirely.
What I'd Do Differently
Implement request coalescing for identical concurrent requests. During high-traffic periods, multiple UI components sometimes requested the same flight status simultaneously. Request coalescing (detecting identical in-flight requests and sharing the response) would have reduced API call volume further. Apollo Client handles this for GraphQL queries, but our REST calls needed manual deduplication.
Add API response contract testing. We relied on Sabre's documentation for response schemas, but documentation occasionally lagged behind actual API behavior. Consumer-driven contract tests that validated actual response shapes against our normalizers would have caught schema changes before they caused production issues.
Build a comprehensive API call dashboard earlier. Debugging integration issues required correlating logs across multiple services. A real-time dashboard showing API call volume, latency percentiles, error rates, and circuit breaker states per domain would have accelerated incident response. We built this eventually, but it should have been part of the initial architecture.
Use a formal API gateway pattern. Our integration layer was a set of service classes within the application. An API gateway (like Kong or a lightweight custom gateway) would have centralized authentication, rate limiting, caching, and circuit breaking at the infrastructure level, reducing the amount of cross-cutting concern code in the application.
FAQ
What are circuit breakers and why use them for API integrations?
Circuit breakers monitor API call failure rates and temporarily stop calling a failing provider when errors exceed a threshold. This prevents cascading failures, reduces latency from timeout waits, and allows the system to fail over to backup providers or cached data automatically. The circuit has three states: closed (normal operation, requests pass through), open (failures exceeded threshold, requests are immediately rejected without calling the upstream), and half-open (after a cooldown period, a limited number of test requests are allowed through to check if the upstream has recovered). For aviation API integrations, this pattern is essential because upstream outages are inevitable, and continuing to send requests to a failing service only makes the situation worse by consuming rate limits and increasing response times.
How do you handle data from multiple aviation API providers?
A normalization layer converts each provider's response format into a unified internal schema. Both Sabre REST and GraphQL endpoints return flight data in different structures with different field names, date formats, and nesting patterns. The normalization functions translate each format into a single NormalizedFlight type that the rest of the application consumes. This means UI components, caching logic, and business rules never need to know which API endpoint provided the data. When an API provider changes their response format, only the corresponding normalization function needs to be updated, isolating the change from the rest of the codebase.
How do you ensure data freshness for real-time flight tracking?
Flight position and status data is polled at 15-second intervals from the upstream API and cached in Redis with TTLs matching the update frequency. The server pushes updates to the frontend through WebSocket connections only when the data has actually changed, avoiding unnecessary renders. A data freshness indicator component displays the age of the displayed data using color-coded labels: green for live data under 15 seconds old, amber for aging data, and red for stale data that exceeds the expected update interval. The stale indicator serves as an explicit warning to operators that the displayed information may not reflect current reality, prompting them to verify through alternate channels before making operational decisions.
Collaboration
Need help with a project?
Let's Build It
I help startups and established companies design, build, and scale world-class digital products. From deep technical architecture to pixel-perfect UI — let's bring your vision to life.
Related Articles
Optimizing Core Web Vitals for e-Commerce
Our journey to scoring 100 on Google PageSpeed Insights for a major Shopify-backed e-commerce platform.
Building an AI-Powered Interview Feedback System
How we built an AI-powered system that analyzes mock interview recordings and generates structured feedback on communication, technical accuracy, and problem-solving approach using LLMs.
Migrating from Pages to App Router
A detailed post-mortem on migrating a massive enterprise dashboard from Next.js Pages Router to the App Router.