An API that is not documented is an API nobody can adopt. This guide covers how Turkish Airlines teams describe their services so that the specification itself — not a wiki page or a Slack thread — becomes the contract consumers build against.
Write an OpenAPI 3.0 description for every service before it is published. Name each operation with an explicit operationId, give every parameter a type and description, and document the error responses as carefully as the success path — consumers spend far more time handling failures than reading the happy path. Keep the specification in the same repository as the service so it is reviewed in the same pull request as the code it describes.
Attach a request and response example to every operation, and use realistic values — a genuine IATA code such as IST, a plausible date, a real cabin class. Examples are the first thing a developer reads and the thing they copy into their client. A placeholder example that returns nothing useful costs your support team more than it saves the author.
openapi: 3.0.3
info:
title: Turkish Airlines Timetable API
version: 1.0.0
paths:
/timetable:
get:
operationId: getTimetable
summary: Retrieve scheduled flights for a route
parameters:
- name: origin
in: query
required: true
schema: { type: string, example: IST }
- name: destination
in: query
required: true
schema: { type: string, example: LHR }
responses:
'200':
description: Scheduled flights for the requested route
Ready to publish?
Once your specification is reviewed and merged, the next step is getting it onto this portal so other teams can discover and consume it.