API adresi ve ortamlar

Sursa API’nin, kişilerin Sursa’yı tarayıcıda açmak için kullandığı adresten ayrı, kendine ait bir adresi vardır. Tüm yollar /v1 ile başlar.

Sursa’nın çalıştığı yer	API adresi	Bu portal
Sursa bulutu	`https://api.sursa.com`	`https://developers.sursa.com`
Kendi kurulumunuz	Yöneticinizin ayarladığı biçimde `https://api.<your domain>`	API adresinde `/developers/`
Ayrı bir API adresi olmayan kurulumunuz	kurulumun ana adresi	ana adreste `/developers/`

API adresi yalnızca API’yi sunar: bu adreste oturum açma sayfası, çerez ya da web arayüzü yoktur. Her istek bir API anahtarıyla ya da bir OAuth erişim belirteciyle doğrulanır. Adrese bir yük dengeleyicinin arkasındaki birden fazla sunucu hizmet verebilir; entegrasyonunuzun bunların kaç tane olduğunu bilmesi gerekmez.

API’yi ana adres üzerinden (örneğin https://app.sursa.com/v1) çağıran entegrasyonlar çalışmaya devam eder. Birkaç farkı ve adım adım geçişi API adresine geçiş kılavuzunda bulabilirsiniz.

Temel URL

Her isteği yapılandırmanızdaki tek bir temel URL’den oluşturun; böylece aynı kod her ortamda çalışır:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Yalnızca HTTPS kullanın ve yaptığınız isteklerin günlüklerine anahtarı yazmayın.

Sürüm ve spesifikasyon

GET /v1/health adresin çalışıp çalışmadığını bildirir ve adrese hizmet veren Sursa sürümünü döndürür. Anahtar olmadan yanıt verir, bu yüzden onu izlemede kullanabilirsiniz:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Bu, API’nin değil, Sursa yayınının sürümüdür. API’nin sürümü, spesifikasyonunun info.version alanıdır. API’nin OpenAPI 3.1 spesifikasyonu aynı adreste, kimlik doğrulama olmadan yayımlanır:

Yol	İçerik
`GET /openapi.json`	Herkese açık spesifikasyon; `servers` alanında bu adres yer alır.
`GET /v1/openapi-public.json`	Aynı spesifikasyon. `ETag` ve `If-None-Match` desteklenir.

Spesifikasyonu bir istemci üretmek, API’yi Postman gibi bir araca aktarmak ya da entegrasyonunuzun yalnızca beklediğiniz sürümün işlemlerini kullandığını CI’da kontrol etmek için kullanın. Bu portalın API başvurusu da aynı dosyadan oluşturulur.

Test etme

Sursa’nın ayrı bir test modu yoktur: anahtarla yapılan her istek, anahtarın kuruluşunun gerçek verileri üzerinde çalışır. Güvenle geliştirmek ve test etmek için:

Geliştirme için, işin gerektirdiği en dar rol ve kapsamlara sahip ayrı bir anahtar oluşturun.
Yalnızca ekibinizin görebildiği, örneğin sandbox adlı ayrı bir koleksiyona yazın ve işiniz bittiğinde onu silin.
Şirketinizin test için ayrı bir Sursa kuruluşu ya da kurulumu varsa temel URL’yi ve anahtarı ona yönlendirin. Kodunuzda başka hiçbir şey değişmez.
Yeniden denemeleri baştan güvenli hâle getirin: her POST ve PATCH isteğiyle bir Idempotency-Key gönderin.

API başvurusunda her uç nokta sayfasındaki Dene konsolu, içine yapıştırdığınız bir anahtarla gerçek istekler gönderir. Anahtar tarayıcı sekmesinin belleğinde kalır ve yalnızca API adresine gönderilir.

Ağ gereksinimleri

Sunucularınızdan API adresine giden HTTPS (443 numaralı bağlantı noktası).
Ağınız izin veriyorsa güvenlik duvarı kurallarında sabit IP adresleri yerine ana makine adına izin verin: kapasite eklendikçe adresin arkasındaki sunucular değişebilir.
Tarayıcı uygulamaları API’yi doğrudan çağırabilir: yanıtlar, çerez kullanmadan her kökene izin verir (Access-Control-Allow-Origin: *). Tarayıcıda kullanılan bir anahtarı o tarayıcının kullanıcısının görebileceğini unutmayın.