REST API

Dove nel portale: Riferimento API su https://<your-domain>/apidoc (pubblico) e chiavi API su /api-keys. Dove nell'amministrazione: Customers › API keys (/customers/apikeys) elenca le chiavi create dai clienti.

Descrizione

Ogni azione che un cliente può compiere nel portale — elencare e gestire VM, leggere fatture, gestire chiavi SSH, Kubernetes, storage, ticket di supporto — è disponibile tramite un'API REST con controllo di versione sotto https://<your-domain>/v1/. I clienti la chiamano da script e CI con una API key con ambito limitato. La stessa API alimenta lo strumento a riga di comando cmp command-line tool e il server MCP server, e il riferimento viene generato dall'installazione in esecuzione, quindi elenca sempre esattamente le funzionalità che hai attivato.

Requisiti

Elemento	Requisito
Indirizzo HTTPS pubblico	L'API è servita sul tuo dominio principale (e sul dominio di ciascun rivenditore).
Una chiave API	Creata dal cliente nel portale; vedi API keys.
Dipendenze	Nessuno. Gli endpoint di un modulo che non hai abilitato (ad esempio Kubernetes o Object Storage) sono nascosti dal riferimento e rifiutati.

Prepara l'infrastruttura

Nulla da installare. Se un proxy inverso si trova davanti a NexCMP, inoltra /v1/, /mcp, /cli/ e /apidoc al pannello (la configurazione nginx del programma di installazione lo fa già).

Collega in NexCMP

Il riferimento interattivo

Apri https://cloud.example.com/apidoc (sostituisci l'host con il tuo dominio; i clienti di un rivenditore vedono il riferimento sul dominio del rivenditore, con il nome del rivenditore). Dispone di documentazione sugli endpoint con esempi di richiesta e risposta in curl, cmp CLI, JavaScript, Python e Go, una casella di ricerca (Ctrl o Cmd + K) e un pannello Try it. Try it invia richieste solo allo stesso sito, con una chiave incollata dal visitatore (mantenuta nella sessione del browser); è di sola lettura per impostazione predefinita e le chiamate di scrittura o a pagamento richiedono un interruttore aggiuntivo e una conferma.

Download e documenti leggibili da macchina

Tutti sono pubblici, non richiedono chiavi e sono generati per sito:

URL	Contenuto
/apidoc	Riferimento interattivo.
/v1/public/openapi.json	Documento OpenAPI 3.1.
/v1/public/openapi.yaml	Stesso, YAML.
/v1/public/postman.json	Raccolta Postman.
/v1/public/insomnia.json	Esportazione Insomnia.
/v1/public/api.md	Il riferimento come singolo file Markdown.
/v1/public/api-catalog	JSON leggero: brand, URL di base, prefisso della chiave, ogni ambito ed ogni endpoint con metodo, percorso, ambito e se richiede un Idempotency-Key.

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

In Postman seleziona Import › Link e incolla https://cloud.example.com/v1/public/postman.json. La pagina di riferimento offre anche client API a file singolo per JavaScript e Python.

Autenticazione

Invia la chiave nell'intestazione Authorization:

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

• Le chiavi dei clienti iniziano con vk_. Le chiavi sono vincolate al sito: una chiave creata su cloud.example.com non funziona sul dominio di un rivenditore.
• I token di sessione del browser (pt_...) sono riservati al portale; usa una chiave per l'automazione.
• Gli ambiti della chiave determinano cosa può chiamare; un ambito mancante risponde con HTTP 403 scope_required. Vedi API keys.
• Verifica una chiave con GET /v1/apikeys/self: restituisce il nome, gli ambiti, la scadenza e il residuo del limite di velocità della chiave chiamante (ciascuna chiave può chiamarla).

Esempi

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

Prendi i campi di richiesta esatti di ciascuna operazione da /apidoc.

Errori

Ogni errore è in formato JSON con un code stabile e un message leggibile dall'utente:

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	Tipico code	Significato
401	unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled	Chiave mancante o sconosciuta, revocata, scaduta, IP del chiamante al di fuori dell'elenco consentito della chiave, chiave proveniente da un altro sito o chiavi API disattivate.
403	scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden	La chiave non ha l'ambito; l'endpoint non è disponibile per le chiavi; l'account è bloccato; è stata raggiunta una quota; azione non consentita in una sessione impersonata.
404	not_found	Non trovato — restituito anche per risorse che appartengono a qualcun altro.
422	invalid_argument	Errore di validazione (campo specificato nella risposta).
429	rate_limited	Troppe richieste; attendi per Retry-After.
503	maintenance	La modalità di manutenzione è attiva: le letture funzionano, le scritture vengono rifiutate.

Limiti di velocità

Limite	Predefinito
Per chiave	120 richieste al minuto
Per account (tutte le chiavi insieme)	300 richieste al minuto

Ogni risposta contiene X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; un errore 429 aggiunge Retry-After.

Idempotency

I comandi che comportano costi o non possono essere ripetuti (creazione, cambio piano, acquisto, eliminazione...) richiedono un'intestazione Idempotency-Key (qualsiasi stringa fino a 200 caratteri; un UUID funziona bene). Invia nuovamente la stessa chiave dopo un timeout e il server restituirà il risultato originale (con Idempotency-Replayed: 1) anziché ripetere l'operazione. Il riutilizzo di una chiave per un comando diverso risponde con 422; una richiesta ancora in corso risponde con 409/Retry-After. Senza l'intestazione, una chiamata a pagamento viene rifiutata.

Verifica

1. Crea una chiave con ambito vm:read nel portale (API keys › Create key).

2. Esegui:

   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

   Ricevi HTTP 200 e le intestazioni relative al limite di velocità.

3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" elenca le macchine virtuali dell'account. Nel portale, la colonna Last used della chiave e il Key usage log mostrano le chiamate.

Limiti e note

• Mai accessibili con una chiave: ricariche, prelievi, modifica delle carte o ricarica automatica, modifica della password, e-mail o 2FA, eliminazione dell'account, creazione, modifica o revoca di altre chiavi. Queste operazioni richiedono una sessione browser attiva.
• Moduli nascosti: il riferimento e il documento OpenAPI elencano solo le funzionalità abilitate su quel sito.
• Dimensione della risposta e paginazione: gli endpoint di elenco sono paginati (page, per_page); leggi il documento OpenAPI per ogni endpoint.
• Tempo e denaro: gli importi sono espressi in centesimi di USD, salvo diversa indicazione nel nome del campo.
• API di amministrazione: la console di amministrazione ha la sua pagina System › Admin › API e chiavi di amministratore (ofw_...) per la gestione; sono separate dalle API per i clienti descritte qui.
• Controllo delle versioni: il prefisso del percorso /v1 è stabile; è possibile che vengano aggiunti nuovi campi alle risposte.

Troubleshooting

Sintomo	Causa	Soluzione
401 su una nuova chiave	Chiave proveniente da un altro dominio, scaduta o inserita con spazi	Crea la chiave sul dominio che chiami; verifica l'header Authorization: Bearer vk_....
403 scope_required	Scope mancante	Modifica la chiave nel portale e aggiungi lo scope.
401 key_ip_denied o site_mismatch	Chiave limitata ad altri IP ("allowed IPs") o creata su un altro dominio	Aggiungi l'IP del tuo server agli IP consentiti della chiave oppure chiama il dominio su cui è stata creata.
404 su una VM esistente	La VM appartiene a un altro account	Usa una chiave del proprietario.
400/422 con richiesta di Idempotency-Key	Operazione a pagamento senza l'header	Aggiungi Idempotency-Key: <uuid>.
429	Limite superato	Riduci la frequenza; usa Retry-After.
/apidoc mostra meno del previsto	Modulo disattivato	Attiva il modulo in License & updates.