Ein Token, erstellt im Kundenpanel
Wird als Bearer-Token gesendet. Beschränken Sie ihn bei Bedarf auf Nur-Lesen oder auf einen einzelnen Dienst; Token sind unabhängig von Ihrem Passwort, und das Widerrufen eines Tokens meldet Sie nie ab.
Ein Token, und alles, was das Kundenpanel kann
JSON über HTTPS. Kein SDK erforderlich, kein separates Entwicklerkonto und kein Endpunkt, der im Kundenpanel existiert, aber nicht hier.
Server erstellen
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Liefert sofort eine Build-ID. Die Maschine antwortet etwa sechzig Sekunden später über SSH, und die Adresse ist geroutet, bevor die Zugangsdaten versendet werden.
20 Endpunkte
Alles, in fünf Gruppen
Basis-URL https://api.vpsoffshore.com/v1. Versioniert im Pfad; v1 funktioniert weiterhin, wenn v2 existiert, und das Datum der Einstellung wird ein Jahr im Voraus angekündigt.
Server
GET
/servers
Jeder Dienst im Konto, mit Status, Tarif und Adressen.
POST
/servers
Erstellen Sie eine. Liefert sofort eine Build-ID zurück; der Server ist etwa eine Minute später erreichbar.
GET
/servers/{id}
Ein Dienst, einschließlich der Live-Ressourcennutzung der letzten Stunde.
PATCH
/servers/{id}
Den Tarif wechseln. Größenänderung ohne Rebuild, soweit die Festplatte es zulässt.
DELETE
/servers/{id}
Vernichten. Festplatten werden 14 Tage aufbewahrt und vor der Wiederverwendung gelöscht.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
Speicher
GET
/servers/{id}/snapshots
Snapshots für einen Dienst, neueste zuerst.
POST
/servers/{id}/snapshots
Nehmen Sie eins. Thin, damit es schnell ist und Ihren Speicherplatzverbrauch nicht verdoppelt.
POST
/snapshots/{id}/restore
Wiederherstellung am selben Ort oder auf einem anderen Dienst desselben oder eines größeren Tarifs.
DELETE
/snapshots/{id}
Einen Snapshot entfernen.
Netzwerk
GET
/servers/{id}/addresses
An einen Dienst geroutete Adressen, v4 und v6.
POST
/servers/{id}/addresses
Fordern Sie eine zusätzliche Adresse an, oder ein /29.
PUT
/addresses/{ip}/rdns
Reverse-DNS festlegen. Wirkt innerhalb einer Minute, nicht erst bei der nächsten Zonenaktualisierung.
GET
/servers/{id}/bandwidth
Transferzähler. Informativ — es gibt kein Kontingent, das überschritten werden könnte.
Katalog
GET
/plans
Jeder Tarif mit seiner Spezifikation und seinem Preis. Dieselbe Quelle, aus der auch diese Website erzeugt wird.
GET
/images
Verfügbare Images und ISOs, einschließlich der von Ihnen hochgeladenen.
POST
/images
Laden Sie ein ISO über eine URL hoch. Startet mit angeschlossener Konsole.
Abrechnung
GET
/invoices
Rechnungen, bezahlt und offen, mit dem Coin und der Chain-Transaktion.
POST
/invoices/{id}/pay
Erzeugt eine Zahlungsadresse für einen der 8 akzeptierten Coins.
GET
/credits
Angewendete SLA-Gutschriften, mit dem jeweils auslösenden Vorfall.
Alles, was das Kundenpanel kann, ist hier vorhanden, und nichts hier fehlt im Kundenpanel. Wenn beide voneinander abweichen, ist das ein Fehler — teilen Sie es uns über das Kundenpanel mit, und es wird behoben statt als beabsichtigtes Verhalten dokumentiert.
Wie es sich verhält
Vier Entscheidungen, die Sie innerhalb einer Stunde bemerken werden
Eine API wird an ihren schlechten Pfaden gemessen, nicht an den guten. Drei der vier unten beschriebenen Punkte handeln davon, was passiert, wenn etwas schiefgeht.
JSON rein, JSON raus, kein SDK nötig
Einfaches HTTPS ohne eigenen Umschlag, ohne XML-Fallback und ohne Signier-Ritual. Wenn curl es kann, haben Sie einen Client. Offizielle Bibliotheken gibt es für Go, Python und TypeScript, und keine davon ist erforderlich.
Rate-Limits, die Sie nicht versehentlich erreichen
600 Anfragen pro Minute und Token, 60 für Erstellungsaufrufe. Jede Antwort enthält das verbleibende Budget in einem Header, und eine Überschreitung liefert 429 mit der Anzahl der zu wartenden Sekunden zurück — nie ein stilles Verwerfen.
Fehlermeldungen, die sagen, was zu tun ist
Ein 4xx enthält einen maschinenlesbaren Code, einen für Menschen verständlichen Satz und das betroffene Feld. Wir geben lieber eine lange Fehlermeldung zurück als eine kurze, bei der Sie raten müssen.
Die zwei Dinge, die Sie einmal schreiben
Authentifizierung, und wie ein Fehler aussieht
Beide lohnt es sich zu lesen, bevor Sie den ersten Aufruf schreiben, statt erst nach dem ersten Fehlschlag.
Authentifizieren
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"Tokens werden im Kundenpanel erstellt und können auf Nur-Lesen oder auf einen einzelnen Dienst beschränkt werden. Sie sind unabhängig von Ihrem Passwort, und das Widerrufen eines Tokens meldet Sie nirgendwo ab.
Lesen Sie das Rate-Limit
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41Bei jeder Antwort, nicht nur bei der, die fehlschlägt. Eine Überschreitung des Limits liefert 429 mit der Anzahl der zu wartenden Sekunden, nie ein stilles Verwerfen und nie eine gekürzte Antwort.
Ein Fehler nennt Ihnen das Feld
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}Ein maschinenlesbarer Code, ein für Menschen verständlicher Satz und das betroffene Feld. Lange Fehlermeldungen sind günstiger als kurze, bei denen Sie raten müssen.
Einen Build abfragen
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .stateGeht von building zu running. Es gibt keinen Webhook, den Sie registrieren müssen, bevor Sie etwas erstellen können, und Polling einmal pro Sekunde liegt innerhalb des Limits.
Nichts zu beantragen
Der Token befindet sich im Kundenpanel, und das Kundenpanel erhalten Sie mit dem ersten Server
Kein Entwicklerkonto, keine Genehmigung, keine Sandbox, die sich anders verhält als die Produktion.
Als Nächstes lesen
Wie es hier weitergeht