Aviation Crew History Data API 1.0.2

Architecture overview

The request flow is:

Client → Apigee X → AWS Lambda (Quarkus) → PostgreSQL

Apigee X is the API gateway. It handles OAuth 2.0 token validation and routes requests to the backend. The backend is an AWS Lambda function built with Quarkus (compiled to a native image) that reads crew history from a PostgreSQL database. Large responses are offloaded to Amazon S3 and served back to the caller through a temporary pre-signed download link.

Base URLs

Authentication

The API uses OAuth 2.0 with the client credentials grant. First obtain an access token from the token endpoint, then send it as a Bearer token on each request.

Token endpoints:

• Non-production: https://test.api.tui/oauth2/token
• Production: https://prod.api.tui/oauth2/token

Available scopes:

• aviation-crew-history.all — full access to all crew history data
• aviation-crew-history.read — read access to all crew history data
• aviation-crew-history.write — write access to all crew history data

Request a token:

curl -X POST https://test.api.tui/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=aviation-crew-history.read"

Call the API with the token:

curl "https://test.api.tui/aviation-crew-history/crew-history?crewId=089294&startDate=2023-01-01&endDate=2023-12-31&includeBlockTime=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Rate limits

No specific rate limits are enforced by this API at present.

Large response handling

When a response would be large, the backend stores it as a JSON file in an S3 bucket and returns a temporary pre-signed download link instead of the inline payload. This happens in two cases:

• The serialised response reaches or exceeds the payload size limit of 5,000,000 bytes (approximately 5 MB).
• The caller explicitly sets responseFile=true on the request.

The pre-signed download link is valid for 1 hour from the time it is generated. Note that the OpenAPI descriptions mention a 60-second window; the deployed backend is configured for a 1-hour expiry.

Data freshness and date range

Data is sourced from the TUI crew tracking system and refreshes at roughly five-minute intervals, so responses are about five minutes behind the live source. The startDate must be the same as or before the endDate, and both must use the yyyy-mm-dd format.

Correlation ID

The backend reads an X-Correlation-Id request header and uses it to correlate log entries for a request. Sending a correlation id makes it easier for the support team to trace a specific call. If the header is absent, the backend generates its own identifier.

Error handling

The API returns standard HTTP status codes. Refer to the interactive specification for the full response schemas.

Requesting access

Access is granted through the TUI air links portal:

1. Go to https://tui-air-links.com.
2. Raise an access request for the Aviation Crew History Data API.
3. On approval you receive OAuth 2.0 client credentials scoped to the API.

Support

• Team: AOPS Tech (airtech-integration)
• Portal: https://tui-air-links.com