API adresine geçiş

Daha önceki entegrasyonlar API’yi Sursa’nın ana adresinden, yani kişilerin tarayıcıda açtığı adresten çağırır, örneğin https://app.sursa.com/v1/…. API’nin artık kendine ait bir adresi de vardır: bulutta https://api.sursa.com, kendi kurulumunuzda https://api.<your domain>. Bu adres entegrasyonlar için tasarlanmıştır: bir yük dengeleyicinin arkasında yatay olarak ölçeklenir ve API dışında hiçbir şey sunmaz.

Geçiş yapmak zorunda değilsiniz. Ana adres, mevcut entegrasyonlar için /v1 yollarını bitiş tarihi ve yönlendirme olmadan sunmaya devam eder. API adresinin avantajlarından yararlanmak için size uygun olduğunda geçin ve her yeni entegrasyonda bu adresi kullanın.

Aynı kalanlar

Yollar, parametreler, alanlar, hata kodları ve olaylar: GET /v1/cards iki adreste de aynı istektir.
API anahtarları. Aynı kb_ ve kbsrc_ anahtarları, aynı rol, kapsamlar ve veri profiliyle iki adreste de çalışır.
Idempotency anahtarları, hız sınırları ve kotalar. İki adrese yapılan istekler de kuruluşun aynı kotalarına sayılır.
Webhook’lar. Teslimler, imzalar ve gizli değerler çağırdığınız adrese bağlı değildir.
Yanıtlardaki bağlantılar. Hangi adresi çağırırsanız çağırın, bir hatanın doc_url alanı bu portala, bir liste sayfasının Link başlığı ise API adresine yönlendirir.

API adresinde farklı olanlar

Ana adreste	API adresinde
Web uygulamasının iç uç noktalar dahil tüm uç noktaları	Yalnızca herkese açık API başvurusundaki uç noktalar. Diğer tüm yollar `api.not_found` koduyla `404` yanıtı verir.
`X-API-Key` ya da `Authorization` başlığında bir anahtar veya bir tarayıcı oturum çerezi	Bir anahtar ya da bir OAuth erişim belirteci, tercihen `Authorization: Bearer` içinde. Çerezler yok sayılır.
`GET /auth/me`	`GET /v1/me`. `/auth/` altındaki yollar sunulmaz.
Çerezle çalışan “View as” modu (başka bir kullanıcı gibi görüntüleme)	`admin` rolüne sahip anahtarlar için `X-View-As` başlığı.
Tek sunucu ya da sabit bir sunucu kümesi	Bir yük dengeleyicinin arkasında birden fazla sunucu.

Son satır yalnızca tek bir durum için önemlidir: POST /v1/chat isteğinin akış hâlindeki yanıtı. Kopan bir akış, Last-Event-ID ile yalnızca yanıtı yazan sunucuda devam eder. Entegrasyonunuz akışları sürdürüyorsa her soruya bir request_id verin; böylece başka bir sunucuya giden yeniden deneme ikinci bir yanıt yerine kaydedilmiş yanıtı alır. Kopan akışı sürdürme bölümüne bakın.

Geçişten önce

Her çağrının herkese açık olduğunu kontrol edin. Entegrasyonunuzun çağırdığı yolları listeleyin ve her birini API başvurusunda arayın ya da yeni adresin spesifikasyonuyla karşılaştırın:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Herkese açık başvuruda bulunmayan bir yol web uygulamasına aittir. Ana adreste hâlâ çalışır, ancak API adresinde sunulmaz ve biçimi herkese açık bir taahhüt değildir. Onu herkese açık bir uç noktayla değiştirin ya da entegrasyonun o bölümünü ana adreste tutun ve neye ihtiyacınız olduğunu Sursa’daki irtibat kişinize bildirin.

Kimlik doğrulama yönteminizi kontrol edin. Entegrasyon bir kullanıcının parolası ve oturum çereziyle oturum açıyorsa önce onu bir API anahtarına geçirin. X-API-Key gönderiyorsa Authorization: Bearer başlığına geçmeniz önerilir, ancak zorunlu değildir.

Ağınızı kontrol edin. Güvenlik duvarınızda ve proxy sunucularınızda yeni ana makine adına giden HTTPS trafiğine izin verin.

Adım adım geçiş

Henüz değilse temel URL’yi entegrasyonunuzun bir ayarı hâline getirin.

Yeni adresi bir okuma isteğiyle deneyin:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Entegrasyonunuzun test paketini bir test anahtarı ve test koleksiyonuyla yeni adrese karşı çalıştırın.
Trafiğin bir bölümünü geçirin, örneğin tek bir işçiyi ya da tek bir ortamı, ve günlüklerinizde 404 api.not_found, 401 ve 5xx yanıtlarını izleyin. Her yanıt X-Request-Id taşır; bu değeri günlüklerinizle birlikte saklayın.
Geri kalanını geçirin. Saniyeler içinde geri dönebilmek için eski temel URL’yi bir süre yapılandırmanızda tutun.

Geçişten sonra kontrol edilecekler

Yeni adresteki GET /v1/health eski adrestekiyle aynı version değerini döndürür.
Yanıtlarda RateLimit başlıkları bulunur. Entegrasyonunuz kendini X-RateLimit-* başlıklarına göre yavaşlatıyorsa bunu sürdürebilir: iki başlık kümesi de gönderilir. Hız sınırları ve kotalar sayfasına bakın.
Entegrasyonunuz tarayıcıda çalışıyorsa artık CORS için kendi proxy sunucunuza ihtiyacı yoktur: API adresi her kökenden gelen isteklere çerez olmadan izin verir.