Technical Information — TUI Aviation Flight Schedule API

Architecture overview

Client → Apigee X Gateway → AWS API Gateway → Lambda (Quarkus Native) → PostgreSQL (IDPS Group Replica)
                                                       ↓ (large responses)
                                                      S3 → Pre-signed URL returned to client

• Gateway: Apigee X handles OAuth 2.0 token validation, scope extraction, and request routing.
• Backend: A Quarkus Native AWS Lambda function processes requests, queries the database, applies scope-based JSON views, and returns the response.
• Data source: PostgreSQL database containing a materialised view of the IDPS flight schedule data (Group Replica).
• Large response handling: When the response payload exceeds the size threshold, the Lambda writes the JSON to S3 and returns a pre-signed download URL.

Base URLs

Authentication

This API uses OAuth 2.0 Client Credentials flow.

Token endpoints

Scopes

• aviation-flight-schedule-internal.all — Full access to all resources
• aviation-flight-schedule-internal.read — Read access to all resources
• aviation-flight-schedule-internal.write — Write access to all resources

Obtain a token

curl -X POST https://test.api.tui/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Call the API

curl -X GET "https://test.api.tui/aviation-flight-schedule/tuigroup/flights?designator=OR&flightNumber=2168&flightDate=2026-08-10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate limits

There are no enforced rate limits at this time. Consumers are expected to use the API responsibly.

Response scoping

The API uses a scope-based view system controlled by the x-app-client-scope header (set automatically by Apigee based on the consuming application's configured flight-schedule.read attribute). There are three tiers:

Without the Sensitive scope, crew member records are still returned (when crewMembers=true) but PII fields are omitted.

Large response handling

The Lambda has a payload size limit of approximately 4.5 MB (conservative threshold below the Lambda runtime hard limit of ~6 MB). When exceeded — or when responseFile=true is passed — the full JSON response is stored on S3 and the API returns a message containing a pre-signed URL.

• Pre-signed URL validity: 1 hour
• Trigger: Automatic when payload ≥ 4.5 MB, or manual via responseFile=true
• Response body: "The results were stored on S3. They can be retrieved here: <url>"

Data freshness and date range

• Data is queried in real-time from the IDPS Group Replica materialised view.
• Available date range: current day − 3 months to current day + 2 months.
• The startDate/endDate range filter uses a COALESCE of actual, estimated, and rescheduled departure date.

Correlation ID

The backend supports request tracing via the following headers (all optional, but recommended):

These headers are logged by the backend and enable end-to-end log correlation across systems.

Error handling

Refer to the OpenAPI spec for full error response examples.

Requesting access

1. Visit https://tui-air-links.com
2. Request access to the Aviation Flight Schedule API
3. Upon approval you will receive client_id and client_secret for the OAuth 2.0 flow
4. Use the credentials to obtain a bearer token and start making requests

Support