API opuściło betę drugiego lipca. Trafiło do platformy w wersji 5.4 w czerwcu, działało jako beta na zaproszenie od lutego z nieco ponad czterystoma kontami, a swojego kształtu nie zmieniało od kwietnia. Z wersjonowaniem, dokumentacją i objęte tym samym zobowiązaniem dostępności co panel.
Nazwanie tego spóźnionym byłoby hojnością. Powód nie jest tajemniczy: interfejs siedzący na systemie provisioningu, który potrzebował trzech i pół minuty na zbudowanie serwera, byłby interfejsem do odpytywania spinnera. Najpierw przepisaliśmy kolejkę, w 2025 roku, a kolejność ta była zamierzona, a nie przypadkowa.
Co robi
| Grupa | Co możesz zrobić | Uwagi |
|---|---|---|
| Instancje | Utwórz, zmień rozmiar, przebuduj, zrób snapshot, przywróć, zniszcz | Zmiana rozmiaru w górę jest na żywo, w dół wymaga jednego reboota |
| Obrazy | Lista katalogu OS, zarejestruj własne ISO po URL | Instalacje z własnego ISO są nadal ręczne i nadal wolne |
| Sieć | Dodaj IPv4, edytuj reverse DNS, zamów IPv6 /48 | Delegowane, nigdy proxowane |
| Filtrowanie | Odczytaj zdarzenia ataków, pushuj reguły warstwy 7 na DDoS Pro | Podstawowe filtrowanie nie ma nic do konfiguracji |
| Billing | Odczytaj saldo, listuj faktury, otwórz fakturę doładowania | Brak pól karty, bo nie ma kart |
| Zdarzenia | Odpytywaj log zdarzeń lub zarejestruj webhook | Podpisany per-konto sekretem |
Wszystko jest JSON przez HTTPS, a każdy obiekt, który panel może pokazać, jest obiektem, który API może zwrócić. Nie ma warstwy funkcji zarezerwowanej dla interfejsu webowego, co jest obietnicą, która nas kosztuje: panel konsumuje teraz te same publiczne endpointy co Ty, więc zepsute API to zepsuty panel i dowiadujemy się o tym natychmiast.
Autoryzacja
Tokeny tworzone są w panelu, z zakresami, i pokazywane dokładnie raz. Bez autoryzacji hasłem, bez ciasteczek sesyjnych, bez przekierowania do dostawcy tożsamości, któremu musielibyśmy zaufać czymś, czego z dużym trudem nie zbieramy.
Token niesie zakres odczytu, zapisu lub bilingu, opcjonalne ograniczenie do jednej lokalizacji, opcjonalne ograniczenie do listy instancji oraz wygaśnięcie, które ustawiasz. Sześćdziesiąt dni to domyślne. Tokeny mogą być odwoływane indywidualnie, a odwołanie jest skuteczne na brzegu w ciągu dwóch sekund, co ma większe znaczenie, niż brzmi, gdy serwer buildowy zostanie przebudowany przez kogoś, kto nie wiedział, co na nim było.
Ponieważ konto tutaj to adres e-mail i hash hasła, nie ma obiektu klienta do pobrania. API nie ma pola nazwy, adresu, firmy ani podatku, dokładnie z tego powodu, dla którego formularz rejestracyjny ich nie ma.
Limity zapytań, idempotencja, błędy
Sześćset odczytów na minutę i sześćdziesiąt zapisów, liczonych per token, a nie per konto, więc jeden hałaśliwy skrypt nie zagłodzi reszty Twojej automatyzacji. Limity zwracane są w nagłówkach przy każdej odpowiedzi, w tym przy udanych.
Każdy zapis przyjmuje klucz idempotencji. Ponów tworzenie z tym samym kluczem, a dostaniesz oryginalną instancję zamiast drugiej, fakturowanej obok. To jest pojedyncza funkcja, za którą beta testerzy dziękowali nam najbardziej, co mówi coś o tym, jak reszta branży radzi sobie z timeoutem podczas provisioningu.
Błędy to udokumentowany kod maszynowy, jedno zdanie, które człowiek może przeczytać, oraz identyfikator żądania. Wklej identyfikator do zgłoszenia, a support zobaczy to samo żądanie co Ty, bez proszenia Cię o jego odtworzenie.
Czego celowo nie robi
- Nigdy fiat. Endpointy billingowe odczytują saldo i otwierają fakturę doładowania. Rozliczenia pozostają w OxaPay i w łańcuchu, który wybrałeś, dokładnie jak opisano na stronie płatności.
- Brak subkont i ról. Ciągle o to proszą. Nie zbudowano, bo oczywista implementacja oznacza trzymanie struktury kto-dla-kogo-pracuje, a wolelibyśmy wysyłać tokeny z zakresami i wygaśnięciem, a strukturę organizacyjną zostawić Tobie.
- Brak autoscalingu. Instancje to dedykowane rdzenie na prawdziwym krzemie, a nie pula, którą możemy wyczarować. Możesz tworzyć i niszczyć według własnego harmonogramu; nie będziemy udawać, że pod spodem jest elastyczna abstrakcja.
- Brak matrycy SDK. Jeden referencyjny klient i zwykły HTTP jako kontrakt. Sześć półutrzymywanych wiązań językowych zestarzałoby się gorzej niż dokumentacja.
Co chcielibyśmy zepsuć
Beta znalazła dziewięć błędów wartych naprawy, z których trzy były nasze w ciekawy sposób, a sześć to kłamstwa dokumentacji. Jeśli znajdziesz dziesiąty, nadużycie limitu zapytań jest w porządku i oczekiwane podczas testów, a support woli identyfikator żądania niż zrzut ekranu.
Referencja jest w dokumentacji. Changelog dla wersji 5.4 wymienia siedem endpointów, które zmieniły kształt między lutym a kwietniem, i to są jedyne breaking change'y, jakie będą w wersji pierwszej.