Un token, generato nel pannello
Inviato come bearer token. È possibile limitarne l'ambito alla sola lettura o a un singolo servizio; i token sono indipendenti dalla password, e revocarne uno non disconnette mai l'account.
Un token, e tutto ciò che il pannello cliente può fare
JSON su HTTPS. Nessun SDK richiesto, nessun account sviluppatore separato, e nessun endpoint presente nel pannello ma non qui.
Creare un server
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Restituisce immediatamente un id di configurazione. La macchina risponde su SSH circa sessanta secondi dopo, e l'indirizzo è instradato prima che le credenziali vengano inviate.
20 endpoint
Tutto, in cinque gruppi
URL di base https://api.vpsoffshore.com/v1. Versionato nel percorso; v1 continuerà a funzionare anche quando esisterà v2, e la data di interruzione sarà annunciata con un anno di anticipo.
Server
GET
/servers
Ogni servizio nell'account, con stato, piano e indirizzi.
POST
/servers
Ne crea uno. Restituisce immediatamente un build id; il server è raggiungibile circa un minuto dopo.
GET
/servers/{id}
Un servizio, incluso l'utilizzo delle risorse in tempo reale dell'ultima ora.
PATCH
/servers/{id}
Cambia il piano. Esegue il ridimensionamento senza reinstallare, dove il disco lo consente.
DELETE
/servers/{id}
Distruggerlo. I dischi vengono conservati per 14 giorni, poi cancellati prima di essere riassegnati.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
Archiviazione
GET
/servers/{id}/snapshots
Snapshot di un servizio, dal più recente.
POST
/servers/{id}/snapshots
Se ne effettua una. È sottile: veloce, e non raddoppia lo spazio su disco.
POST
/snapshots/{id}/restore
Ripristino sul posto, oppure su un servizio diverso dello stesso piano o superiore.
DELETE
/snapshots/{id}
Rimuovere uno snapshot.
Rete
GET
/servers/{id}/addresses
Indirizzi instradati verso un servizio, v4 e v6.
POST
/servers/{id}/addresses
Richiedere un indirizzo aggiuntivo, o un /29.
PUT
/addresses/{ip}/rdns
Impostare il reverse DNS. Ha effetto entro un minuto, non al successivo aggiornamento della zona.
GET
/servers/{id}/bandwidth
Contatori di trasferimento. Informativi — non esiste una soglia da superare.
Catalogo
GET
/plans
Ogni piano con la relativa specifica e il relativo prezzo. La stessa fonte da cui è generato questo sito.
GET
/images
Immagini e ISO disponibili, incluse quelle caricate dal cliente.
POST
/images
Carichi un'ISO tramite URL. Si avvia con una console collegata.
Fatturazione
GET
/invoices
Fatture, pagate e in sospeso, con la moneta e la transazione on-chain.
POST
/invoices/{id}/pay
Genera un indirizzo di pagamento per una delle 8 monete accettate.
GET
/credits
Crediti SLA applicati, con l'incidente che ha generato ciascuno.
Tutto ciò che il pannello cliente può fare è qui, e nulla qui manca nel pannello cliente. Quando i due non coincidono si tratta di un bug — ce lo segnali dal pannello cliente e viene corretto invece di essere documentato come comportamento previsto.
Come si comporta
Quattro decisioni che si notano entro un'ora
Un'API si giudica dai suoi percorsi peggiori, non da quelli migliori. Tre delle quattro voci seguenti riguardano cosa succede quando qualcosa va storto.
JSON in ingresso, JSON in uscita, nessun SDK necessario
HTTPS puro, senza involucro personalizzato, senza fallback XML e senza rituali di firma. Se può farlo curl, Lei ha già un client. Esistono librerie ufficiali per Go, Python e TypeScript, e nessuna di esse è obbligatoria.
Limiti di frequenza che non si raggiungono per errore
600 richieste al minuto per token, 60 per le chiamate di creazione. Ogni risposta include il budget residuo in un header, e superarlo restituisce 429 con il numero di secondi da attendere — mai uno scarto silenzioso.
Errori che indicano cosa fare
Un 4xx contiene un codice leggibile da una macchina, una frase comprensibile e il campo responsabile dell'errore. Preferiamo restituire un errore lungo piuttosto che uno breve da indovinare.
Le due cose che si scrivono una sola volta
Autenticazione, e come si presenta un errore
Entrambi meritano una lettura prima di scrivere la prima chiamata, non dopo il primo errore.
Autenticarsi
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"I token vengono creati nel pannello e possono essere limitati alla sola lettura o a un singolo servizio. Sono indipendenti dalla password, e revocarne uno non disconnette da nessuna parte.
Consultare il rate limit
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41Su ogni risposta, non solo su quella che fallisce. Il superamento del limite restituisce un 429 con i secondi di attesa, mai un blocco silenzioso e mai una risposta troncata.
Un errore indica il campo
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}Un codice leggibile da una macchina, una frase comprensibile e il campo responsabile dell'errore. Gli errori lunghi costano meno di quelli brevi che si devono indovinare.
Interrogazione di una configurazione
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statePassa da building a running. Non è necessario registrare alcun webhook prima di poter creare qualcosa, e un polling di una volta al secondo rientra nel limite.
Nulla da richiedere
Il token si trova nel pannello, e il pannello viene fornito con il primo server
Nessun account sviluppatore, nessuna approvazione, nessun sandbox che si comporti diversamente dalla produzione.