Technical Information
Architecture overview
The Aviation Crew Master Data API follows this request flow:
Client → Apigee X (OAuth + routing) → AWS Lambda (Quarkus native) → PostgreSQL (IDPS replica)- API gateway: Apigee X handles OAuth 2.0 token validation, client scope resolution, and request routing.
- Backend: An AWS Lambda function built with Quarkus (native image) running in
eu-central-1. - Data source: A read replica of the IDPS crew tracking database (PostgreSQL). Data refreshes approximately every five minutes.
- Large responses: When the JSON payload exceeds 5 MB, or when
responseFile=trueis set, the response is stored in S3 and a pre-signed download URL (valid for 60 seconds) is returned instead.
Base URLs
| Environment | URL |
|---|---|
| Development | https://dev.api.tui/aviation-crew-master-data |
| Test (SIT) | https://test.api.tui/aviation-crew-master-data |
| Production | https://prod.api.tui/aviation-crew-master-data |
Authentication
OAuth 2.0 Client Credentials flow. Obtain a token from the relevant token endpoint, then pass it as a Bearer token on every request.
| Environment | Token URL |
|---|---|
| Non-production | https://test.api.tui/oauth2/token |
| Production | https://prod.api.tui/oauth2/token |
Example: 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" \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "client_secret=<YOUR_CLIENT_SECRET>" \
-d "scope=aviation-crew-master-data.read"Example: call the API
curl -X GET "https://test.api.tui/aviation-crew-master-data/crews-info?\
startDate=2026-01-01&endDate=2026-12-31&owner=TUI&flat=true" \
-H "Authorization: Bearer <ACCESS_TOKEN>"Rate limits
No per-client rate limits are enforced. The serverless architecture scales automatically with request volume.
Response scoping
The API returns different field sets depending on the scope tier assigned to your application by the AOPS Tech team. Scope is resolved from your app's registered attributes in Apigee — you do not need to pass it explicitly.
| Tier | Fields included |
|---|---|
| standard (default) | crewId, staffId, threeLetterCode, owner, employmentStartDate, employmentEndDate, seniority, plus all optional collections (homebases, ranks, fleet, expiries, airport expiries, travel documents, visas, contracts) |
| extended | Everything in standard, plus surname, givenName, gender, dateOfBirth, crewEmail, crewPhoneNumber, additionalInfo |
| sensitive | Everything in extended (reserved for future PII fields) |
If your application needs fields from a higher tier, request a scope upgrade via https://tui-air-links.com.
Large response handling
When any of these conditions are met, the API writes the full JSON to S3 and returns a lightweight response with a download link:
- The serialised JSON exceeds 5 MB, or
- The caller sets
responseFile=true.
The response body in this case looks like:
{
"message": "The response payload exceeds the size limit or was explicitly requested to be stored in S3.",
"extended_response_file": "https://s3.eu-central-1.amazonaws.com/..."
}The pre-signed URL expires after 60 seconds. Download the file immediately or request a new one.
Data freshness and date range
- The IDPS replica refreshes approximately every 5 minutes.
- The supported query date range is one year before to one year after the current date.
Correlation ID
Pass an X-Correlation-Id header with your request to trace it through logs. If
omitted, the backend generates one automatically. The same ID appears in Apigee
and Lambda logs for end-to-end tracing.
Error handling
The API uses standard HTTP status codes. See the OpenAPI specification for full error response schemas. In summary:
| Status | When it happens |
|---|---|
| 200 | Success — data returned inline or via S3 link |
| 204 | Query matched no records — body contains { "data": [] } |
| 401 | Token missing, expired or invalid |
| 403 | Token valid but lacks the required scope |
| 500 | Unexpected backend error |
| 504 | Lambda or database did not respond within the gateway timeout |
Requesting access
- Visit https://tui-air-links.com.
- Select the System Access option.
- Name the API product:
aviation-crew-master-data. - Include a brief business case.
The AOPS Tech team reviews requests and provisions client credentials on approval.
Support
- Team: AOPS Tech (airtech-integration)
- Portal: https://tui-air-links.com
- Email: aops.airlineit@tui.com
