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
OpenAPI belgesi OpenAPI 3.1 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 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.