API Versioning
Once an API is published, someone depends on it. Versioning is how Turkish Airlines evolves a service without breaking the integrations already in production — and how consumers know, ahead of time, what is about to change.
What counts as breaking
Removing a field, renaming a field, narrowing a type, adding a required parameter, or changing the meaning of an existing value are all breaking changes, and all require a new major version. Adding an optional parameter or a new field to a response is not breaking, provided existing clients ignore fields they do not recognise. When in doubt, assume a consumer is parsing your response strictly — because one of them is.
Run versions side by side
Ship a new major version on its own path and run it alongside the previous one. Announce the deprecation date when the new version launches, not when you want the old one gone, and send it to the registered owner of every application still calling the old path. The gateway reports per-version traffic, so you can see who is still on the old version and confirm it is genuinely unused before you retire it.
Code sample
bash
# v1 and v2 served side by side during the deprecation window
curl https://api.turkishairlines.com/v1/availability \
-H "Authorization: Bearer $TOKEN"
# v2 adds an optional cabin filter — additive, non-breaking
curl https://api.turkishairlines.com/v2/availability \
-H "Authorization: Bearer $TOKEN" \
-G --data-urlencode "cabin=business"
# Deprecation is advertised on the response itself
# Deprecation: true
# Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Browse the catalog
See the APIs Turkish Airlines publishes today, with the full interactive specification for each one.