Un piano di controllo più tranquillo.

Un modello di risorse chiaro

Un'integrazione dovrebbe funzionare con identificatori di server, regioni, immagini, piani e operazioni espliciti. Le richieste di creazione e reinstallazione dovrebbero restituire un'operazione che può essere verificata fino al completamento. Una richiesta HTTP riuscita non equivale a una macchina pronta.

Credenziali con un compito limitato

I token API dovrebbero essere revocabili in modo indipendente e limitati alle risorse e azioni minime necessarie. Conservali in un secret manager o in un ambiente protetto. Non inviare mai un token al browser solo per evitare di scrivere un piccolo backend.

I tentativi ripetuti devono essere sicuri

I timeout di rete possono verificarsi dopo che un'operazione è stata accettata. Usa una chiave di idempotenza per le richieste di creazione e sensibili ai pagamenti, ispeziona lo stato dell'operazione e rispetta i limiti di frequenza. Un nuovo tentativo dovrebbe risolvere l'incertezza, non creare un server fatturabile aggiuntivo.

Verifica la compatibilità prima dell'integrazione

Verifica la versione API rilasciata, il modello di autenticazione, i formati degli errori, la paginazione, i limiti di frequenza e gli ambiti dei token prima di realizzare un'integrazione. Usa solo pacchetti KoalaVPS SDK pubblicati da link di rilascio verificati.

Roadmap di API

La roadmap di API copre individuazione del catalogo, autenticazione, stato dell'account, fatturazione crypto, ciclo di vita del server, chiavi SSH pubbliche e webhook. Le rotte seguenti descrivono il contratto dell'interfaccia; l'accesso alla produzione non è ancora disponibile.

Rotte di autenticazione e account

Il contratto API separa le sessioni di accesso e le chiavi API. Verifica gli schemi di risposta, gli errori, la durata dei token e le azioni di ripristino supportate rispetto alla versione rilasciata per la tua integrazione.

• 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

Catalogo e percorsi di fatturazione

La consultazione del catalogo non deve richiedere un pagamento. La creazione del pagamento richiede un ambito di fatturazione limitato, uno stato della fattura chiaro e una gestione idempotente. La conferma deve essere completata prima dell'attivazione del servizio.

• 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 e rotte di accesso

Il ciclo di vita richiede una conferma esplicita per le operazioni di cancellazione e reinstallazione. Le chiavi SSH private appartengono al client; il servizio necessita solo delle loro controparti pubbliche.

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

Eventi e informazioni pubbliche

I webhook richiedono firme verificabili, tentativi limitati e protezione dalla riproduzione. Gli endpoint di fiducia pubblici dovrebbero restituire prove reali e datate anziché rassicurazioni sintetiche.

• 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

Autorizzazione e limiti di traffico

Un modello di ambito candidato è lettura, server, fatturazione e completo, con un massimo di dieci chiavi attive per account. Il contratto API propone budget di richieste di 120 al minuto e 3,000 all'ora per una chiave API, e 30 al minuto per il traffico pubblico. Verifica HTTP 429, Retry-After e la finestra di applicazione nella documentazione API rilasciata; questi budget della roadmap non costituiscono un impegno sulla capacità di produzione.

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

SDK e rilasci del protocollo

La roadmap di integrazione include REST, un endpoint MCP ospitato, un pacchetto stdio con versione, SDK e una CLI. Verifica la disponibilità delle release, i runtime supportati, i checksum e la compatibilità con API prima di installare un client. I download per la produzione non sono ancora disponibili.

Risorse API, raggruppate per responsabilità

Il API previsto separa l'accesso all'account, la lettura del catalogo, la fatturazione, il ciclo di vita del server, le chiavi SSH e i callback. Le chiamate in sola lettura non dovrebbero creare un ordine e una credenziale di fatturazione non dovrebbe autorizzare automaticamente modifiche alla sicurezza dell'account. Questo descrive il contratto di integrazione. Un endpoint di provisioning di produzione e un SDK rilasciato non sono disponibili tramite questo sito.

• Account: sessioni, utilizzo ed eventi di controllo della sicurezza
• Catalogo: piani, regioni e immagini disponibili
• Server: creazione, ispezione, modifica e annullamento
• Chiavi SSH: registra il materiale pubblico e revoca le chiavi obsolete
• Webhook: registra, ispeziona, testa e rimuovi callback firmati

Una richiesta al server dovrebbe restare contenuta

Scegli un identificatore di piano standard, una regione, un'immagine del sistema operativo e un hostname. Il limite previsto per l'hostname è di 64 caratteri. Un servizio live può generare privatamente un segreto amministratore o accettare una chiave pubblica SSH registrata. Aggiunte arbitrarie di disco, GPU, NIC e IP non sono implicite in una richiesta di piano standard. Rifiuta i campi non supportati invece di addebitare silenziosamente un upgrade ipotizzato.

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

Ambiti e limiti delle chiavi fanno parte del contratto

I gruppi di privilegi proposti sono lettura, server, fatturazione e amministrazione completa dell'account. Una chiave dovrebbe essere mostrata una sola volta alla creazione, conservata privatamente e revocata indipendentemente dalla password dell'utente. Il limite previsto per l'account è di dieci chiavi attive. Prima di pubblicare un'implementazione, verifica che ogni operazione rifiuti una chiave priva dell'ambito richiesto.

Pubblica insieme i limiti di frequenza e il comportamento di retry

I limiti proposti sono 120 richieste al minuto e 3,000 all'ora per una chiave API, e 30 richieste al minuto per le richieste pubbliche non autenticate al catalogo. Questi sono valori di policy pianificati, non capacità API misurata. Un'implementazione live richiede una risposta 429 coerente, indicazioni Retry-After e un backoff client limitato. Anche le richieste di creazione e pagamento richiedono chiavi di idempotenza stabili.

I webhook sono messaggi che possono arrivare più di una volta

Un ricevitore di callback dovrebbe verificare la firma sul corpo originale, rifiutare i timestamp al di fuori della finestra consentita e ricordare gli identificatori degli eventi elaborati. Persisti l'evento prima di confermarlo, poi applica la modifica in modo idempotente. Mantieni visibili i tentativi di consegna e un percorso di riproduzione manuale. Un callback è un'osservazione su un'operazione, non un'autorizzazione a eseguire istruzioni non correlate contenute in un payload.

Esegui l'audit senza trasformare i log in un archivio segreto

Registra l'identificatore dell'attore, il tipo di operazione, la risorsa interessata, il risultato e l'ora quando necessario per la sicurezza dell'account. Evita per impostazione predefinita di registrare password, token bearer, chiavi private o corpi completi di richieste di pagamento e applicative. Mantieni espliciti conservazione, accesso e cronologia visibile al cliente. Una traccia di audit di sicurezza e una pretesa di ispezionare i contenuti applicativi del cliente sono cose diverse.

Rilascia gli artefatti solo quando esistono

Un lancio pubblico di API dovrebbe includere un documento OpenAPI versionato, istruzioni di autenticazione, esempi di errori e un processo di deprecazione. Una futura CLI, un pacchetto Python, un client TypeScript o un server MCP richiede un rilascio effettivo, checksum e documentazione mantenuta. Un pacchetto di provisioning KoalaVPS o un endpoint di gestione di produzione non viene rilasciato tramite questo sito.

Un po' più di chiarezza.