Eine ruhigere Control Plane.

Ein klares Ressourcenmodell

Eine Integration sollte mit expliziten Serverkennungen, Regionen, Images, Tarifen und Vorgängen arbeiten. Erstellungs- und Neuinstallationsanfragen sollten einen Vorgang zurückgeben, der bis zum Abschluss geprüft werden kann. Eine erfolgreiche HTTP-Anfrage ist nicht dasselbe wie eine betriebsbereite Maschine.

Zugangsdaten mit einer begrenzten Aufgabe

API-Tokens sollten unabhängig widerrufbar und auf die minimal benötigten Ressourcen und Aktionen beschränkt sein. Speichern Sie sie in einem Secret-Manager oder einer geschützten Umgebung. Senden Sie ein Token niemals an den Browser, nur um ein kleines Backend zu vermeiden.

Wiederholungen müssen sicher sein

Netzwerk-Timeouts können auftreten, nachdem ein Vorgang angenommen wurde. Verwenden Sie einen Idempotenzschlüssel für Erstellungs- und zahlungssensible Anfragen, prüfen Sie den Vorgangsstatus und beachten Sie Ratenlimits. Ein Wiederholungsversuch sollte Unsicherheit auflösen, nicht einen zusätzlichen abrechenbaren Server erzeugen.

Kompatibilität vor der Integration prüfen

Prüfen Sie die veröffentlichte Version API, das Authentifizierungsmodell, Fehlerformate, Paginierung, Ratenbegrenzungen und Token-Berechtigungsbereiche, bevor Sie eine Integration erstellen. Verwenden Sie ausschließlich veröffentlichte KoalaVPS SDK-Pakete aus verifizierten Release-Links.

API-Roadmap

Die API-Roadmap umfasst Katalogerkennung, Authentifizierung, Kontozustand, Krypto-Abrechnung, Server-Lebenszyklus, öffentliche SSH-Schlüssel und Webhooks. Die folgenden Routen beschreiben den Schnittstellenvertrag; Produktionszugriff ist noch nicht verfügbar.

Authentifizierungs- und Kontorouten

Der Vertrag von API trennt Anmeldesitzungen und API-Schlüssel. Prüfen Sie Antwortschemata, Fehler, Token-Lebensdauern und unterstützte Wiederherstellungsaktionen gegen die für Ihre Integration veröffentlichte Version.

• 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- und Abrechnungswege

Katalogabfragen sollten keine Zahlung erfordern. Die Zahlungserstellung benötigt einen eingeschränkten Abrechnungsbereich, einen klaren Rechnungsstatus und eine idempotente Verarbeitung. Die Bestätigung muss vor der Dienstaktivierung abgeschlossen sein.

• 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

Server- und Zugangswege

Der Lebenszyklus erfordert eine ausdrückliche Bestätigung für Stornierungs- und Neuinstallationsvorgänge. Private SSH-Schlüssel gehören auf den Client; der Dienst benötigt nur deren öffentliche Gegenstücke.

• 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}

Veranstaltungen und öffentliche Informationen

Webhooks benötigen überprüfbare Signaturen, begrenzte Wiederholungsversuche und Replay-Schutz. Öffentliche Vertrauens-Endpunkte sollten echte, datierte Nachweise zurückgeben statt synthetischer Zusicherungen.

• 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

Autorisierung und Verkehrsgrenzen

Ein mögliches Berechtigungsmodell ist Lesen, Server, Abrechnung und Vollzugriff, mit maximal zehn aktiven Schlüsseln pro Konto. Der API-Vertrag schlägt Anfragebudgets von 120 pro Minute und 3,000 pro Stunde für einen API-Schlüssel sowie 30 pro Minute für öffentlichen Datenverkehr vor. Prüfen Sie HTTP 429, Retry-After und das Durchsetzungsfenster in der veröffentlichten API-Dokumentation; diese Roadmap-Budgets sind keine Produktionskapazitätszusage.

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

SDK und Protokollversionen

Die Integrations-Roadmap umfasst REST, einen gehosteten MCP-Endpunkt, ein versioniertes stdio-Paket, SDKs und eine CLI. Prüfen Sie die Verfügbarkeit der Releases, unterstützte Laufzeitumgebungen, Prüfsummen und die API-Kompatibilität, bevor Sie einen Client installieren. Produktions-Downloads sind noch nicht verfügbar.

API-Ressourcen, nach Verantwortlichkeit gruppiert

Die vorgesehene API trennt Kontozugriff, Kataloglesen, Abrechnung, Server-Lebenszyklus, SSH-Schlüssel und Callbacks. Schreibgeschützte Aufrufe sollten keine Bestellung erstellen, und ein Abrechnungsnachweis sollte nicht automatisch Änderungen an der Kontosicherheit autorisieren. Dies beschreibt den Integrationsvertrag. Ein Produktions-Provisioning-Endpunkt und ein veröffentlichtes SDK sind über diese Website nicht verfügbar.

• Konto: Sitzungen, Nutzung und Sicherheitsprüfungsereignisse
• Katalog: Tarife, Regionen und verfügbare Images
• Server: erstellen, prüfen, ändern und kündigen
• SSH-Schlüssel: öffentliches Material registrieren und veraltete Schlüssel widerrufen
• Webhooks: signierte Callbacks registrieren, prüfen, testen und entfernen

Eine Serveranfrage sollte klein bleiben

Wählen Sie eine Standard-Plan-Kennung, eine Region, ein Betriebssystem-Abbild und einen Hostnamen. Das vorgesehene Hostnamen-Limit beträgt 64 Zeichen. Ein laufender Dienst kann ein Administratorgeheimnis privat erzeugen oder einen eingetragenen öffentlichen Schlüssel SSH akzeptieren. Beliebige Ergänzungen von Festplatte, GPU, NIC und IP sind mit einer Standard-Plan-Anfrage nicht impliziert. Lehnen Sie nicht unterstützte Felder ab, statt stillschweigend für ein vermutetes Upgrade zu berechnen.

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

Scopes und Schlüssellimits sind Teil des Vertrags

Die vorgeschlagenen Berechtigungsgruppen sind Lesen, Server, Abrechnung und vollständige Kontoverwaltung. Ein Schlüssel sollte bei der Erstellung einmal angezeigt, privat gespeichert und unabhängig vom Passwort des Benutzers widerrufen werden. Das vorgesehene Kontolimit liegt bei zehn aktiven Schlüsseln. Bevor Sie eine Implementierung veröffentlichen, prüfen Sie, dass jeder Vorgang einen Schlüssel ohne den erforderlichen Berechtigungsumfang ablehnt.

Veröffentlichen Sie Ratenlimits und Wiederholungsverhalten gemeinsam

Die vorgeschlagenen Limits sind 120 Anfragen pro Minute und 3,000 pro Stunde für einen API-Schlüssel sowie 30 Anfragen pro Minute für nicht authentifizierte öffentliche Kataloganfragen. Dies sind geplante Richtwerte, keine gemessene API-Kapazität. Eine Live-Implementierung benötigt eine konsistente 429-Antwort, Retry-After-Hinweise und begrenztes Client-Backoff. Erstellungs- und Zahlungsanfragen benötigen zudem stabile Idempotenzschlüssel.

Webhooks sind Nachrichten, die mehr als einmal ankommen können

Ein Callback-Empfänger sollte die Signatur über den ursprünglichen Body verifizieren, Zeitstempel außerhalb seines zulässigen Fensters ablehnen und verarbeitete Ereignis-IDs merken. Speichern Sie das Ereignis dauerhaft, bevor Sie es bestätigen, und wenden Sie die Änderung dann idempotent an. Halten Sie Zustellversuche und einen manuellen Wiederholungspfad sichtbar. Ein Callback ist eine Beobachtung zu einer Operation, keine Berechtigung, unzusammenhängende Anweisungen in einer Nutzlast auszuführen.

Prüfen, ohne Logs in einen geheimen Speicher zu verwandeln

Erfassen Sie die Akteur-ID, den Vorgangstyp, die betroffene Ressource, das Ergebnis und den Zeitpunkt, soweit für die Kontosicherheit erforderlich. Vermeiden Sie standardmäßig die Erfassung von Passwörtern, Bearer-Tokens, privaten Schlüsseln oder vollständigen Zahlungs- und Anwendungsanfrageinhalten. Halten Sie Aufbewahrung, Zugriff und kundensichtbaren Verlauf ausdrücklich fest. Ein Sicherheits-Audit-Trail und ein Anspruch auf Einsicht in Kundenanwendungsinhalte sind verschiedene Dinge.

Artefakte erst veröffentlichen, wenn sie existieren

Ein öffentlicher API-Start sollte ein versioniertes OpenAPI-Dokument, Authentifizierungsanweisungen, Fehlerbeispiele und einen Deprecation-Prozess umfassen. Eine künftige CLI, ein Python-Paket, ein TypeScript-Client oder ein MCP-Server benötigt eine tatsächliche Veröffentlichung, Prüfsummen und gepflegte Dokumentation. Ein KoalaVPS-Provisionierungspaket oder ein Produktionsverwaltungs-Endpunkt wird über diese Website nicht veröffentlicht.

Etwas mehr Klarheit.