Tutti gli endpoint restituiscono application/json. Gli errori seguono RFC 7807 (Problem+JSON). Ogni risposta contiene un header X-Request-Id per la correlazione con l'audit log lato server.
| Method | Path | Permesso | Scopo |
|---|---|---|---|
| GET | /v1/health | public | Health check non autenticato. |
| GET | /v1/me | any | Informazioni del proprio account e metadati chiave. |
| GET | /v1/products | read:products | Elenco di tutti i prodotti pubblicamente disponibili con prezzi. |
| GET | /v1/products/{id} | read:products | Dettagli prodotto incluse opzioni di configurazione. |
| POST | /v1/orders | write:orders | Effettuare un ordine. Idempotency-Key obbligatoria. |
| GET | /v1/orders/{id} | read:orders | Stato di un proprio ordine. |
| GET | /v1/services | read:services | Elenco dei propri servizi (paginato). |
| GET | /v1/services/{id} | read:services | Dettagli di un proprio servizio. |
| GET | /v1/services/{id}/credentials | read:credentials | Credenziali del servizio (permesso separato, registrato in audit). |
| POST | /v1/services/{id}/actions | write:services | Azione sul servizio: start, stop, reboot, reinstall, suspend, unsuspend, terminate. |
| GET | /v1/billing/balance | read:billing | Saldo credito. |
| GET | /v1/billing/invoices | read:billing | Elenco delle sue fatture (paginato). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | PDF della fattura. |
| GET | /v1/webhooks | read:webhooks | URL del webhook corrente. |
| PUT | /v1/webhooks | write:webhooks | Impostare o rimuovere l'URL del webhook. |
Idempotenza
POST /v1/orders e POST /v1/services/{id}/actions richiedono un header Idempotency-Key (1-80 caratteri da [A-Za-z0-9_.-]). Il server memorizza in cache risposta e hash del body per 24h; una seconda richiesta con stessa chiave e stesso body restituisce la stessa risposta, una seconda richiesta con stessa chiave ma body differente viene rifiutata con 409 idempotency_conflict.
Limiti di velocità
Predefinito: 60 richieste/minuto (con burst 20) e 5000/giorno per chiave, più 600 richieste/minuto per IP indipendentemente dalla chiave. In caso di superamento, HTTP 429 con header Retry-After. Gli header di risposta X-RateLimit-Remaining e X-RateLimit-Reset mostrano lo stato corrente.
