ServerNet API Referansı: Uç Noktalar, Token ve Hız Sınırlaması

Son isteğiniz 401 Unauthorized ile döndüyse ve token'ı doğru kopyaladığınızdan eminseniz, sorun muhtemelen başka bir yerde: Authorization başlığını yanlış önekle gönderdiniz veya token'ı IP'si allowlist'te olmayan bir ortamdan kullanıyorsunuz. Bu metin, ne istediğini bilen ve yalnızca kesin değeri ve resmi davranışı gereken kişi için yazılmıştır.

Token ile kimlik doğrulama: başlığa gerçekte ne gidiyor

Çerez yok, session yok, HMAC imzası yok. Her istekte yalnızca bir başlık vardır:

Authorization: Bearer snc_live_9f3a...c41d
Content-Type: application/json

Bearer öneki büyük-küçük harfe duyarlıdır. Küçük harfli bearer, 401 verir ve yanıt gövdesinde sorunun harflerden kaynaklandığını anlamanızı sağlayacak hiçbir şey söylemez. Bunu destek kayıtlarında çok gördüm.

Token'lar iki türdür: kaynaklar üzerinde gerçek işlemler için snc_live_ ve yalnızca sandbox ortamına karşı çalışan ve gerçek kaynaklar üzerinde 403 döndüren snc_test_. Test token'ını CI'ya koyun, production sunucusuna değil.

Her token'ın bir scope'u vardır. Yalnızca compute:read yetkisi olan bir token, POST /v1/instances için 403 Forbidden yanıtı alır, 401 değil. Bu iki kod arasındaki fark önemlidir: 401 kimliğini tanımadım demektir, 403 tanıdım ama iznin yok demektir. İzleme sisteminiz bu ikisini aynı kabul ediyorsa, işe yaramaz uyarılar üretiyorsunuz demektir.

Hizmet kesintisi olmadan token rotasyonu

Her hesap aynı anda iki aktif token'a sahip olabilir. Doğru sıra şudur: yeni token oluşturun, hizmeti onunla ayağa kaldırın, trafiği taşıyın, sonra eski token'ı revoke edin. Önce revoke ederseniz, uçuştaki istekler 401 ile düşer ve retry logic'iniz yoksa grafikte bir hata aralığı görürsünüz.

Revoke edilen token anında geçersiz olur; sunucu tarafında önbellek yoktur. Bunu retry tasarımında göz önünde bulundurun.

Uç noktalar: /v1 altında ne var

Her şey versiyonlanmıştır. /v1 olmadan yol mevcut değildir ve redirect değil, 404 verir. Bu kasıtlıdır.

İnsanın vaktini alan nokta: POST /v1/instances 202 Accepted ile döner ve gövdesinde id bulunur, ancak sunucu henüz fiilen mevcut değildir. Hemen GET yaparsanız, 404 alabilirsiniz. status building'den running'e geçene kadar poll etmeniz gerekir. Tipik aralık 30 ila 90 saniye arasındadır ve bölgeye ve plan boyutuna bağlıdır.

Küme ayağa kaldırma veya veritabanı ile web arasında özel ağ bağlantısı gibi daha ağır altyapı işleri için bu API yalnızca kabuğu oluşturur; geri kalan iş Sunucular arası özel ağ; internet olmadan güvenli veritabanı ve web iletişimi bölümünde açıklanmıştır.

Hız sınırlaması: sayılar ve başlıklar

Varsayılan üst sınır token başına dakikada 60 istek ve IP başına dakikada 600 istektir. Hangisi önce devreye girer? Hangisi kendi sınırına daha erken ulaşırsa. Bir token'ı on hizmet arasında paylaşırsanız, pratikte her birinin payı dakikada altı istek olur ve birçok kişinin hazırlıksız yakalandığı yer tam burasıdır.

Her yanıt şu başlıkları taşır:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1718032440
Retry-After: 12

X-RateLimit-Reset bir Unix timestamp'tir, saniye sayısı değil. Bunu "sıfırlanmaya kalan saniye" olarak okursanız, backoff mantığınız anlamsız hale gelir. Retry-After yalnızca 429 yanıtında gelir ve doğrudan kullanmanız gereken şeydir.

Yazma işlemlerinin ayrı ve daha katı bir sınırı vardır: dakikada 20 istek. Nedeni açıktır; sunucu oluşturma hypervisor üzerinde ağır bir işlemdir. Arka arkaya 50 sunucu oluşturan bir provisioning script'iniz varsa, 429 ile uykuya yatar. Doğru yol, yazma istekleri arasında en az üç saniye aralıkla kuyruklamaktır, paralelliği artırmak değil.

Burada hata yapıyorlar

Ticket'larda gördüğüm yaygın hata: biri 429 alır, retry'ı sıfır gecikmeyle bir döngüye koyar ve sonra "API kesintide" diye şikayet eder. Bizim taraftaki loglarda görünen şey, hız penceresini sürekli dolu tutan ve sizi pratikte üst sınırın dışına çıkarmayan eşzamanlı istek patlamasıdır. Belirtisi şudur: hata grafiği sıçramalı değil, düz ve süreklidir. Hata sürekliyse, sorun ağ değil hız sınırıdır.

Çözüm: jitter'lı exponential backoff ve Retry-After'a saygı. Bir kez kodda yazın, her yerde kullanın.

Hata yanıtı formatı: parse ettiğiniz şey

Tüm hatalar, istisnasız, tek bir biçime sahiptir:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many write requests. Retry after 12 seconds.",
    "request_id": "req_8c21f0a9b7e4",
    "details": [
      { "field": "region", "issue": "unavailable" }
    ]
  }
}

Koşulu code üzerine koyun, message üzerine değil. Mesaj metni değişebilir; kod kalıcıdır. request_id'yi kendi loglarınıza kaydedin. O olmadan, ticket açtığınızda sizin belirli isteğinizi bulamayız ve konuşma iki gün sürer.

Doğrulama hataları 400 değil, 422 döndürür. details dizisi tam olarak hangi alanın sorunlu olduğunu söyler. Parser'ınız yalnızca message'ı okuyorsa, bu bilgiyi çöpe atıyorsunuz.

Hangi kodu nerede beklemelisiniz

• 400 — JSON gövdesi bozuk veya Content-Type yanlış.
• 401 — Token yok, süresi dolmuş veya Bearer öneki yanlış.
• 403 — Token geçerli ama scope'u yetersiz.
• 404 — Kaynak mevcut değil veya yol sürümü (/v1) eksik.
• 409 — Durum çakışması; örneğin kapanmakta olan bir sunucuyu yeniden başlatma.
• 422 — Alan doğrulaması reddedildi.
• 429 — Hız sınırı.
• 5xx — Bizim tarafımız. Backoff ile retry izinlidir.

İnce bir tuzak: 409'u retry etmeyin. Sunucu geçiş durumundaysa, isteği tekrarlamak durumu daha da kötüleştirir. Geçiş bitene kadar durumu poll etmelisiniz.

Pratikte karşılaşacağınız sınırlamalar

API otomasyon için tasarlanmıştır, anlık izleme için değil. Her 5 saniyede 200 sunucunun durumunu sormak istiyorsanız, bunu yapmayın; bunun yerine webhook veya sunucunun kendi tarafında izleme kurun. Bulut izleme; bulut altyapısında pratik izleme ve uyarı rehberi tam da bu durum için yazılmıştır ve API hız sınırını aşmaz.

İkinci sınırlama: sayfalama. GET /v1/instances sayfa başına en fazla 100 öğe verir ve "hepsini ver" filtresi yoktur. 100'den fazla kaynağınız varsa, döngü kurmanız gerekir. Varsayılan sıralama oluşturma zamanına göre azalandır, bu yüzden yeni kaynaklar her zaman ilk sayfadadır.

Üçüncü ve daha önemli sınırlama: silme işlemi geri alınamaz. DELETE /v1/instances/{id} anında yürütülür ve disk de silinir. Riskli değişikliklerden önce snapshot almadıysanız, geri döndürecek bir şey yoktur. Bulut ortamında snapshot; riskli değişikliklerden önce kurtarıcı yöntemini ilk silme script'inizden sonra değil, önce okuyun.

Hangi yöntemi seçmeliyim: ham API mi resmi araç mı

Yalnızca birkaç sunucunuz varsa ve işleriniz tekrarlıysa, CLI'yi seçin. Daha hızlı sonuç alırsınız ve token yönetimi ile backoff'u kendiniz yazmanız gerekmez. Provisioning bir pipeline'ın parçasıysa veya onlarca kaynak arasında koordinasyon kurmanız gerekiyorsa, ham API'yi seçin; ancak ilk günden retry ve kuyruklama katmanını ciddiye alın.

Seçimin açıkça yanlış olduğu durum: ayda bir kez yapılan işler için API kullanmak. Bunlar için kod yazmak ve bakımını yapmak, panelde üç tıklamadan daha maliyetlidir.

Kendi kendine ölçeklenen iş yükleri için, API üzerinde ölçekleme mantığı yazmak yerine yönetilen Kubernetes kullanın ve ölçeklemeyi ona bırakın. Yalnızca kaynakları kesintisiz olarak artırıp azaltmak istiyorsanız, Kesintisiz bulut kaynak ölçekleme; pratik altyapı yükseltme rehberi daha kesin bir yol sunar. Ve tüm altyapınızı sıfırdan kuruyorsanız, Bulut altyapısı (IaaS) her şeyi ham API üzerinde inşa etmekten daha mantıklı bir başlangıç noktasıdır.

Sık sorulan sorular

Doğru token'a rağmen neden 401 yanıtı alıyorum?

Üç yaygın nedeni vardır. Birincisi, Bearer öneki küçük harfle yazılmıştır. İkincisi, snc_test_ token'ı gerçek bir kaynak üzerinde kullanılmıştır ki doğru yanıtı 403'tür ancak bazı arayüzler bunu 401 olarak gösterir. Üçüncüsü, token revoke edilmiştir ve sunucu tarafında önbellek olmadığı için anında geçersizdir.

Üçünü de elediyseniz, yanıtın request_id'sini alın ve onunla takip edin. Bu tanımlayıcı olmadan, sizin belirli isteğinizi bulmak pratikte imkansızdır.

ServerNet API hız sınırı ne kadar ve nasıl aşabilirim?

Varsayılan üst sınır token başına dakikada 60 istek ve IP başına dakikada 600 istektir. Yazma işlemlerinin ayrı bir dakikada 20 istek sınırı vardır. Aşmanın bir yolu yoktur ve aşmaya çalışmak pencereyi dolu tutar ve durumu daha da kötüleştirir.

Yapmanız gerekenler: Retry-After başlığını doğrudan okuyun, yazma istekleri arasında en az üç saniye aralık bırakın ve token'ı hizmetler arasında paylaşmayın. Sürekli izleme için de API'yi poll etmek yerine webhook kullanın.

API üzerinden sunucu silme geri alınabilir mi?

Hayır. DELETE /v1/instances/{id} anında yürütülür ve sunucunun diski de silinir. Herhangi bir geri dönüşüm kutusu veya saklama süresi yoktur.

Herhangi bir silme script'inden önce snapshot alın. Çalışan sunucudan snapshot almak izinlidir ve bu, on dakikalık bir olay ile kaybedilen bir gün arasındaki farktır.

Sunucu oluşturma yanıtı neden 201 değil de 202?

Çünkü sunucu oluşturma asenkron bir işlemdir. 202 yanıtı isteğin kabul edildiği anlamına gelir, kaynağın oluşturulduğu değil. Gövde id içerir ancak sunucu hâlâ building durumundadır.

running'e ulaşana kadar GET /v1/instances/{id} ile durumu poll etmelisiniz. Bu aralık genellikle 30 ila 90 saniye arasındadır. 202'den hemen sonra GET isteği yaparsanız, 404 alabilirsiniz ve bu normaldir.