---
title: "Document APIs"
url: "https://thy-portal.apim.eu/guides/document-apis"
image: "https://thy-portal.apim.eu/_og/d/c_Ocean.takumi,title_Document+APIs,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNlODE5MzIifX19,p_Ii9ndWlkZXMvZG9jdW1lbnQtYXBpcyI,s_fvNVotOWCZGVCiUc.png"
---

# Document APIs

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.

## [Describe the contract in OpenAPI](#describe-the-contract-in-openapi)

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.

## [Make examples real](#make-examples-real)

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.

## Code sample

yaml

```yaml
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.

[Publish your API](https://thy-portal.apim.eu/guides/publish-apis)