Aviation Crew Roster Data API 1.3.0

Architecture overview

Client → Apigee X → Lambda (Quarkus) → PostgreSQL (crew roster materialized views)

Requests are received by Apigee X, which handles authentication and CORS, then forwards the request to an AWS Lambda function built with Quarkus. The Lambda queries PostgreSQL materialized views that are populated from the TUI crew tracking system. For large result sets, the Lambda writes the response to S3 and returns a pre-signed download URL instead of the JSON body directly.

Base URLs

Authentication

This API uses OAuth 2.0 Client Credentials. Request a token from the appropriate token URL using your client ID and secret, then send it as a Bearer token on subsequent requests.

Token URLs:

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

Available scopes: aviation-crew-roster.all, aviation-crew-roster.read, aviation-crew-roster.write.

Requesting a token:

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

Calling the API with the token:

curl -X GET \
  "https://test.api.tui/aviation-crew-roster/crews-roster-duties?owner=TUI&startDate=2023-01-01&endDate=2023-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate limits

No rate limits are currently enforced on this API.

Large response handling

If the JSON response would exceed roughly 5 MB, or if the responseFile query parameter is explicitly set to true, the Lambda writes the result to S3 instead of returning it inline. The response body then contains a message with a pre-signed URL to download the file. The pre-signed URL is valid for 1 hour.

Data freshness and date range

Roster data is sourced from materialized views that are refreshed from the TUI crew tracking system approximately every five minutes. There is no enforced limit on the date range you can query, but narrower ranges will return faster and are recommended for back-office polling use cases.

Correlation ID

Requests can include an X-Correlation-Id header. When a response is stored on S3 because it is too large, this correlation ID is used to name the stored files, which makes it easier to trace a specific request end to end.

Error handling

See the interactive OpenAPI spec for the full response schemas and examples per endpoint.

Requesting access

Request access through https://tui-air-links.com. Include the environment and scopes you need so the request can be provisioned correctly.

Support

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