Jeden token, wygenerowany w panelu
Przesyłany jako token bearer. Można ograniczyć jego zakres do trybu tylko do odczytu lub do jednej usługi; tokeny są niezależne od hasła, a unieważnienie jednego nigdy nie powoduje wylogowania.
Jeden token, i wszystko, co potrafi panel
JSON przez HTTPS. Bez wymaganego SDK, bez osobnego konta deweloperskiego i bez endpointu, który istnieje w panelu, a nie tutaj.
Utworzyć serwer
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Zwraca identyfikator konfiguracji natychmiast. Maszyna odpowiada na SSH około sześćdziesięciu sekund później, a adres jest routowany, zanim zostaną wysłane dane dostępowe.
20 endpointów
Wszystko w pięciu grupach
Bazowy URL https://api.vpsoffshore.com/v1. Wersjonowane w ścieżce; v1 będzie nadal działać, gdy pojawi się v2, a data zakończenia zostanie ogłoszona z rocznym wyprzedzeniem.
Serwery
GET
/servers
Każda usługa na koncie — wraz ze stanem, planem i adresami.
POST
/servers
Wystarczy ją utworzyć — odpowiedź natychmiast zawiera identyfikator konfiguracji (build id), a serwer jest dostępny mniej więcej minutę później.
GET
/servers/{id}
Jedna usługa, wraz z bieżącym zużyciem zasobów z ostatniej godziny.
PATCH
/servers/{id}
Zmiana planu. Zmiana rozmiaru bez przebudowy tam, gdzie pozwala na to dysk.
DELETE
/servers/{id}
Zniszczyć go. Dyski są przechowywane przez 14 dni, a następnie czyszczone przed ponownym wydaniem.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
Przestrzeń dyskowa
GET
/servers/{id}/snapshots
Migawki dla jednej usługi, od najnowszej.
POST
/servers/{id}/snapshots
Wystarczy jedna migawka. Jest cienka (thin), dzięki czemu jest szybka i nie podwaja zajętości dysku.
POST
/snapshots/{id}/restore
Przywrócenie w tym samym miejscu albo na innej usłudze tego samego planu lub większego.
DELETE
/snapshots/{id}
Usunąć migawkę.
Sieć
GET
/servers/{id}/addresses
Adresy routowane do usługi, w wersjach v4 i v6.
POST
/servers/{id}/addresses
Poprosić o dodatkowy adres lub pulę /29.
PUT
/addresses/{ip}/rdns
Ustawić odwrotny DNS. Zmiana obowiązuje w ciągu minuty, a nie dopiero po kolejnym odświeżeniu strefy.
GET
/servers/{id}/bandwidth
Liczniki transferu. Mają charakter informacyjny — nie ma limitu, który można by przekroczyć.
Katalog
GET
/plans
Każdy plan wraz ze specyfikacją i ceną. To samo źródło, z którego renderowana jest ta strona.
GET
/images
Dostępne obrazy i pliki ISO, w tym te przesłane samodzielnie.
POST
/images
Przesyłanie obrazu ISO przez adres URL. Rozruch z podłączoną konsolą.
Rozliczenia
GET
/invoices
Faktury, opłacone i zaległe, wraz z coinem i transakcją w łańcuchu bloków.
POST
/invoices/{id}/pay
Wystawia adres płatności dla jednego z 8 akceptowanych coinów.
GET
/credits
Zastosowane rekompensaty SLA, wraz z incydentem, który spowodował każdą z nich.
Wszystko, co potrafi panel, jest tutaj, a nic tutaj nie jest pominięte w panelu. Gdy te dwa miejsca się rozmijają, to błąd — zgłoś to z poziomu panelu, a zostanie naprawiony, zamiast zostać udokumentowany jako zamierzone działanie.
Jak to działa
Cztery decyzje widoczne w ciągu godziny
API ocenia się po jego złych ścieżkach, nie po dobrych. Trzy z czterech poniższych punktów dotyczą tego, co dzieje się, gdy coś idzie nie tak.
JSON na wejściu, JSON na wyjściu, bez potrzeby SDK
Zwykłe HTTPS bez własnej koperty, bez XML jako rozwiązania zapasowego i bez rytuału podpisywania. Jeśli potrafi to zrobić curl, dostępny jest klient. Oficjalne biblioteki istnieją dla Go, Python i TypeScript, ale żadna z nich nie jest wymagana.
Limity zapytań, których nie da się przekroczyć przypadkiem
600 żądań na minutę na token, 60 dla wywołań tworzących zasoby. Każda odpowiedź zawiera pozostały limit w nagłówku, a jego przekroczenie zwraca kod 429 wraz z liczbą sekund do odczekania — nigdy ciche odrzucenie.
Błędy, które mówią, co zrobić
Odpowiedź 4xx zawiera kod czytelny maszynowo, zdanie zrozumiałe dla człowieka oraz pole, którego dotyczy błąd. Wolimy zwrócić długi komunikat o błędzie niż krótki, którego znaczenia trzeba się domyślać.
Dwie rzeczy zapisywane tylko raz
Uwierzytelnianie i jak wygląda błąd
Oba warto przeczytać przed napisaniem pierwszego wywołania, a nie po pierwszym niepowodzeniu.
Uwierzytelnij
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"Tokeny są tworzone w panelu i mogą zostać ograniczone do trybu tylko do odczytu lub do jednej usługi. Są niezależne od hasła, a unieważnienie jednego z nich nie powoduje wylogowania z żadnej sesji.
Zapoznać się z limitem zapytań
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41W każdej odpowiedzi, nie tylko w tej, która kończy się błędem. Przekroczenie limitu zwraca kod 429 wraz z liczbą sekund do odczekania — nigdy ciche odrzucenie, nigdy skrócona odpowiedź.
Błąd wskazuje pole
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}Kod czytelny maszynowo, zdanie zrozumiałe dla człowieka i pole, którego dotyczy błąd. Długie komunikaty błędów są tańsze niż krótkie, które trzeba odgadywać.
Sprawdzanie statusu konfiguracji
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statePrzechodzi ze stanu building w stan running. Nie trzeba rejestrować żadnego webhooka, zanim będzie można cokolwiek utworzyć, a odpytywanie raz na sekundę mieści się w limicie.
Nie trzeba się o nic ubiegać
Token znajduje się w panelu, a panel klient otrzymuje wraz z pierwszym serwerem
Brak konta deweloperskiego, brak zatwierdzania, brak środowiska testowego, które działa inaczej niż produkcja.