Daha sakin bir kontrol düzlemi.

Net bir kaynak modeli

Bir entegrasyon açık sunucu tanımlayıcıları, bölgeler, imajlar, planlar ve işlemlerle çalışmalıdır. Oluşturma ve yeniden kurma talepleri, tamamlanana kadar kontrol edilebilecek bir işlem döndürmelidir. Başarılı bir HTTP talebi, bir makinenin hazır olmasıyla aynı şey değildir.

Sınırlı işi olan kimlik bilgileri

API belirteçleri bağımsız olarak iptal edilebilir olmalı ve gereken minimum kaynak ve eylemlerle sınırlandırılmalıdır. Bunları bir gizli yöneticide veya korumalı ortamda saklayın. Küçük bir arka uç yazmaktan kaçınmak için bir belirteci asla tarayıcıya göndermeyin.

Yeniden denemeler güvenli olmalı

Bir işlem kabul edildikten sonra ağ zaman aşımları oluşabilir. Oluşturma ve ödemeye duyarlı istekler için bir idempotency anahtarı kullanın, işlem durumunu inceleyin ve hız sınırlarına uyun. Bir yeniden deneme belirsizliği gidermeli, ekstra faturalandırılabilir bir sunucu oluşturmamalıdır.

Entegrasyondan önce uyumluluğu kontrol edin

Bir entegrasyon oluşturmadan önce yayımlanan API sürümünü, kimlik doğrulama modelini, hata biçimlerini, sayfalamayı, hız sınırlarını ve belirteç kapsamlarını kontrol edin. Yalnızca doğrulanmış sürüm bağlantılarından yayımlanmış KoalaVPS SDK paketlerini kullanın.

API yol haritası

API yol haritası katalog keşfini, kimlik doğrulamayı, hesap durumunu, kripto faturalandırmayı, sunucu yaşam döngüsünü, genel SSH anahtarlarını ve webhook'ları kapsar. Aşağıdaki rotalar arayüz sözleşmesini tanımlar; üretim erişimi henüz mevcut değildir.

Kimlik doğrulama ve hesap rotaları

API sözleşmesi oturum açma oturumlarını ve API anahtarlarını ayırır. Yanıt şemalarını, hataları, belirteç ömürlerini ve desteklenen kurtarma eylemlerini entegrasyonunuz için yayımlanan sürüme göre kontrol edin.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Katalog ve faturalama yolları

Katalog okumaları ödeme gerektirmemelidir. Ödeme oluşturma, kısıtlı bir faturalama kapsamı, net bir fatura durumu ve idempotent işleme gerektirir. Onay, hizmet etkinleştirilmeden önce tamamlanmalıdır.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Sunucu ve erişim rotaları

Yaşam döngüsü, iptal ve yeniden kurulum işlemleri için açık onay gerektirir. Özel SSH anahtarları istemcide bulunmalıdır; hizmetin yalnızca bunların genel karşılıklarına ihtiyacı vardır.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

Etkinlikler ve kamuya açık bilgiler

Webhook'lar doğrulanabilir imzalar, sınırlı yeniden denemeler ve yeniden oynatma koruması gerektirir. Genel güven uç noktaları sentetik güvenceler yerine gerçek tarihli kanıtlar döndürmelidir.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Yetkilendirme ve trafik sınırları

Aday kapsam modeli okuma, sunucular, faturalama ve tam olup hesap başına en fazla on etkin anahtardır. API sözleşmesi, bir API anahtar için dakikada 120 ve saatte 3,000, genel trafik için dakikada 30 istek bütçesi önerir. Yayımlanan API belgelerinde HTTP 429, Retry-After ve uygulama penceresini kontrol edin; bu yol haritası bütçeleri üretim kapasitesi taahhüdü değildir.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK ve protokol sürümleri

Entegrasyon yol haritası REST, barındırılan bir MCP uç noktası, sürümlenmiş bir stdio paketi, SDK ve bir CLI içerir. Bir istemci kurmadan önce sürüm kullanılabilirliğini, desteklenen çalışma zamanlarını, sağlama toplamlarını ve API uyumluluğunu kontrol edin. Üretim indirmeleri henüz mevcut değil.

Sorumluluğa göre gruplandırılmış API kaynakları

Amaçlanan API, hesap erişimini, katalog okumayı, faturalamayı, sunucu yaşam döngüsünü, SSH anahtarlarını ve geri çağırmaları ayırır. Salt okunur çağrılar sipariş oluşturmamalı ve bir faturalama kimlik bilgisi hesap güvenliği değişikliklerini otomatik olarak yetkilendirmemelidir. Bu, entegrasyon sözleşmesini açıklar. Üretim sağlama uç noktası ve yayımlanmış SDK bu site aracılığıyla mevcut değildir.

• Hesap: oturumlar, kullanım ve güvenlik denetimi olayları
• Katalog: planlar, bölgeler ve mevcut görüntüler
• Sunucular: oluştur, incele, değiştir ve iptal et
• SSH anahtarları: genel materyali kaydedin ve kullanımdan kalkmış anahtarları iptal edin
• Web kancaları: imzalı geri çağırmaları kaydedin, inceleyin, test edin ve kaldırın

Bir sunucu isteği küçük kalmalı

Standart bir plan tanımlayıcısı, bölge, işletim sistemi imajı ve ana bilgisayar adı seçin. Amaçlanan ana bilgisayar adı sınırı 64 karakterdir. Canlı bir hizmet, yönetici sırrını özel olarak oluşturabilir veya kayıtlı bir SSH genel anahtarını kabul edebilir. Standart bir plan talebiyle rastgele disk, GPU, NIC ve IP eklemeleri kastedilmez. Desteklenmeyen alanları sessizce tahmini bir yükseltme için ücretlendirmek yerine reddedin.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Kapsamlar ve anahtar sınırları sözleşmenin bir parçasıdır

Önerilen ayrıcalık grupları okuma, sunucular, faturalandırma ve tam hesap yönetimidir. Bir anahtar oluşturulduğunda bir kez gösterilmeli, özel olarak saklanmalı ve kullanıcının parolasından bağımsız olarak iptal edilmelidir. Amaçlanan hesap sınırı on etkin anahtardır. Bir uygulamayı yayımlamadan önce, her işlemin gerekli kapsamı olmayan bir anahtarı reddettiğini doğrulayın.

Hız sınırlarını ve yeniden deneme davranışını birlikte yayımlayın

Önerilen limitler, bir API anahtarı için dakikada 120 ve saatte 3,000 istek, kimliği doğrulanmamış genel katalog istekleri için ise dakikada 30 istektir. Bunlar planlanan politika değerleridir, ölçülmüş API kapasitesi değildir. Canlı bir uygulama tutarlı bir 429 yanıtı, Retry-After yönlendirmesi ve sınırlı istemci geri çekilmesi gerektirir. Oluşturma ve ödeme istekleri ayrıca kararlı idempotency anahtarlarına ihtiyaç duyar.

Webhook'lar birden fazla kez gelebilen mesajlardır

Bir geri çağrı alıcısı, imzayı orijinal gövde üzerinde doğrulamalı, izin verilen penceresi dışındaki zaman damgalarını reddetmeli ve işlenen olay tanımlayıcılarını hatırlamalıdır. Olayı onaylamadan önce kalıcı hale getirin, ardından değişikliği idempotent biçimde uygulayın. Teslimat denemelerini ve manuel yeniden oynatma yolunu görünür tutun. Bir geri çağrı, bir işlem hakkında gözlemdir; bir yükün içerdiği ilgisiz talimatları yürütme izni değildir.

Günlükleri gizli bir depoya dönüştürmeden denetleyin

Hesap güvenliği için gerektiğinde aktör tanımlayıcısını, işlem türünü, etkilenen kaynağı, sonucu ve zamanı kaydedin. Varsayılan olarak parolaları, taşıyıcı belirteçleri, özel anahtarları veya tam ödeme ve uygulama istek gövdelerini kaydetmekten kaçının. Saklama, erişim ve müşteriye görünür geçmişi açık tutun. Bir güvenlik denetim izi ile müşteri uygulama içeriklerini inceleme iddiası farklı şeylerdir.

Yapıtları yalnızca var olduklarında yayınlayın

Herkese açık bir API lansmanı sürümlenmiş bir OpenAPI belgesi, kimlik doğrulama talimatları, hata örnekleri ve bir kullanımdan kaldırma süreci içermelidir. Gelecekteki bir CLI, Python paketi, TypeScript istemcisi veya MCP sunucusu gerçek bir sürüm, sağlama toplamları ve sürdürülen belgeler gerektirir. Bir KoalaVPS sağlama paketi veya üretim yönetim uç noktası bu site üzerinden yayınlanmaz.

Biraz daha netlik.