# Postman koleksiyonu ve OpenAPI belgesi

KeenAuth, makine tarafından okunabilir API sözleşmesini iki dosya olarak yayımlar. İkisi de her sürümde genel yönetim API tanımından üretilir, bu nedenle her zaman API referansıyla eşleşir. Dahili işlemler bu dosyalarda yer almaz.

| Dosya | Biçim | İndirme |
|---|---|---|
| Postman koleksiyonu | Postman Collection v2.1.0 | [postman_collection.json](/api/postman_collection.json) |
| OpenAPI belgesi | OpenAPI 3.1 | [openapi.json](/api/openapi.json) |

## Postman'e içe aktarma

1. Postman'de **Import** seçeneğini belirleyin ve indirdiğiniz `postman_collection.json` dosyasını seçin.
2. Koleksiyon değişkenlerini açın ve `apiKey` değerini bir yönetim API anahtarı olarak ayarlayın. Anahtarı kontrol panelinde veya CLI ile oluşturun; anahtar Bearer belirteci olarak gönderilir.
3. `region` değerini ortamınızın bölgesine ayarlayın (varsayılan `eu`). İstekler `api.{{region}}.keenauth.com` ana makinesine ve `/v1` yoluna gider.
4. Bir istek gönderin. Her `POST` isteği, Postman'in yeni bir GUID ile doldurduğu bir `Idempotency-Key` üstbilgisi taşır; bu sayede yeniden denenen istek güvenlidir.

İstekler API etiketi başına bir klasörde gruplanır. `{{user_id}}` gibi yol parametreleri koleksiyon değişkenleridir; ihtiyaç duyan bir isteği göndermeden önce bunları ayarlayın.

## OpenAPI belgesini kullanma

OpenAPI belgesi; kod üretimi, API ağ geçitleri, linter'lar ve sahte (mock) sunucular için girdi olarak kullanılır. Aynı belge, API'nin kendisi tarafından `https://api.eu.keenauth.com/v1/openapi.json` adresinde de sunulur.

## Sözleşme arşivi ve SDK özetleri

OpenAPI belgesi ayrıca içeriğe dayalı bir arşiv yolunda da yayımlanır. Yol segmenti belge baytlarının SHA-256 özetidir; bu nedenle bir arşiv yolundaki dosya asla değişmez:

| Dosya | İçerik |
|---|---|
| `/openapi/<sha256>/openapi.json` | Belge; ilgili sürümün `/api/openapi.json` dosyasıyla bayt bayt aynıdır |
| `/openapi/<sha256>/openapi.json.sha256` | `sha256sum` biçiminde özet |
| [`/openapi/index.json`](/openapi/index.json) | Arşivlenmiş belgeler: `sha256`, `info_version`, `path`; en güncel olanı `current` ile işaretlenir |

Her sunucu SDK'sı, üretildiği belgenin özetini kaydeder:

| SDK | Konum |
|---|---|
| Node.js (`@keenauth/node`) | `OPENAPI_SHA256` dışa aktarımı ve `package.json` içinde `keenauth.openapiSha256` |
| Python (`keenauth-python`) | `keenauth.OPENAPI_SHA256` ve paket meta verilerindeki `OpenAPI document` proje bağlantısı |
| Go | `keenauth.OpenAPISHA256` |

İndirmeyi doğrulamak için iki dosyanın bulunduğu klasörde `sha256sum -c openapi.json.sha256` komutunu çalıştırın. Özeti, SDK'nizin bildirdiği değerle karşılaştırarak SDK'nın hangi API sürümüne karşı oluşturulduğunu görün.