Jeden token, vytvořený v panelu
Odesílá se jako bearer token. Můžete si ho omezit na režim jen pro čtení nebo na jedinou službu; tokeny jsou nezávislé na vašem heslu a zneplatnění jednoho z nich vás nikdy neodhlásí.
Jeden token, a vše, co umí panel
JSON přes HTTPS. Není potřeba žádné SDK, žádný samostatný vývojářský účet ani endpoint, který by existoval v panelu, ale tady ne.
Vytvořte server
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Okamžitě vrátí ID sestavení. Stroj odpoví na SSH zhruba za šedesát sekund a adresa je routovaná dřív, než jsou odeslány přihlašovací údaje.
20 endpointů
Vše v pěti skupinách
Základní URL https://api.vpsoffshore.com/v1. Verze je součástí cesty; v1 bude fungovat i po vzniku v2 a datum, kdy přestane fungovat, bude oznámeno rok předem.
Servery
GET
/servers
Všechny služby na účtu, se stavem, tarifem a adresami.
POST
/servers
Vytvoří se. Ihned vrátí ID sestavení; server je dostupný přibližně o minutu později.
GET
/servers/{id}
Jedna služba, včetně aktuálního využití zdrojů za poslední hodinu.
PATCH
/servers/{id}
Změna tarifu. Změna velikosti bez přeinstalace tam, kde to disk umožňuje.
DELETE
/servers/{id}
Zničit ho. Disky se uchovávají 14 dní a poté jsou před opětovným použitím vymazány.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
Úložiště
GET
/servers/{id}/snapshots
Snapshoty jedné služby, od nejnovějšího.
POST
/servers/{id}/snapshots
Pořiďte jeden. Je tenký, takže je rychlý a nezdvojnásobí využití disku.
POST
/snapshots/{id}/restore
Obnovení na místě, nebo na jinou službu se stejným nebo vyšším tarifem.
DELETE
/snapshots/{id}
Odstranit snapshot.
Sítě
GET
/servers/{id}/addresses
Adresy routované ke službě, v4 i v6.
POST
/servers/{id}/addresses
Vyžádejte si další adresu nebo blok /29.
PUT
/addresses/{ip}/rdns
Nastavte reverzní DNS. Projeví se do minuty, ne až při dalším obnovení zóny.
GET
/servers/{id}/bandwidth
Počítadla přenosu. Informativní — neexistuje žádný limit, který by šlo překročit.
Katalog
GET
/plans
Každý tarif s jeho specifikací a cenou. Stejný zdroj, ze kterého tento web čerpá.
GET
/images
Dostupné obrazy systémů a soubory ISO, včetně těch, které jste nahráli.
POST
/images
Nahrajte ISO přes URL. Spouští se s připojenou konzolí.
Fakturace
GET
/invoices
Faktury, uhrazené i neuhrazené, s mincí a transakcí na blockchainu.
POST
/invoices/{id}/pay
Vygeneruje platební adresu pro jednu z 8 přijímaných mincí.
GET
/credits
Uplatněné kompenzace SLA, s incidentem, který každou z nich způsobil.
Vše, co umí panel, je i zde, a nic zde nechybí v panelu. Pokud se ty dva neshodují, jde o chybu — dejte nám vědět z panelu a opravíme to, místo abychom to zdokumentovali jako zamýšlené chování.
Jak se to chová
Čtyři rozhodnutí, kterých si všimnete do hodiny
API se posuzuje podle svých špatných cest, nikoli podle těch dobrých. Tři ze čtyř bodů níže popisují, co se stane, když se něco pokazí.
JSON na vstupu, JSON na výstupu, žádné SDK není potřeba
Obyčejné HTTPS bez vlastní obálky, bez záložního režimu XML a bez rituálu podepisování. Pokud to zvládne curl, máte klienta. Oficiální knihovny existují pro Go, Python a TypeScript, a žádná z nich není povinná.
Limity četnosti požadavků, na které nenarazíte omylem
600 požadavků za minutu na token, 60 pro vytvářecí volání. Každá odpověď nese v hlavičce zbývající rozpočet a jeho překročení vrátí 429 s počtem sekund, které je třeba počkat — nikdy tiché zahození.
Chyby, které říkají, co dělat
Chyba 4xx obsahuje strojově čitelný kód, srozumitelnou větu a pole, kterého se týká. Raději vrátíme dlouhou chybovou zprávu než krátkou, u které musíte hádat.
Dvě věci, které napíšete jednou
Ověřování a jak vypadá chyba
Obojí se vyplatí přečíst před napsáním prvního volání, ne až po prvním selhání.
Ověřit se
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"Tokeny se vytvářejí v panelu a lze je omezit jen na čtení nebo na jednu službu. Jsou nezávislé na vašem hesle a odvolání jednoho vás nikde neodhlásí.
Přečtěte si rate limit
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41Na každé odpovědi, nejen na té, která selže. Překročení limitu vrátí 429 s počtem sekund, které je třeba počkat, nikdy tichým zahozením a nikdy zkrácenou odpovědí.
Chyba označí příslušné pole
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}Strojově čitelný kód, srozumitelná věta a pole, kde nastala chyba. Dlouhé chybové hlášky jsou levnější než krátké, u kterých musíte hádat.
Dotazujte se na stav konfigurace
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statePřechází z building do running. Není třeba registrovat žádný webhook, než něco vytvoříte, a dotazování jednou za sekundu je v rámci limitu.
Nic, o co byste museli žádat
Token najdete v panelu a panel dostanete spolu s prvním serverem
Žádný vývojářský účet, žádné schvalování, žádný sandbox, který by se choval jinak než produkce.