API-Schnellstart

API-Schlüssel erstellen

Öffnen Sie in der Cloud-Konsole die Einstellungen Ihrer Organisation und wählen Sie unter Manage API Keys die Option Create an API Key. Die Konsole zeigt den Schlüssel nur einmal bei seiner Erstellung; kopieren Sie ihn daher vor dem Schließen des Dialogs.

Jede Anfrage in der Dokumentation zeigt ihn als <api-key> im Header Authorization: Bearer. Setzen Sie dort Ihren Schlüssel ein und ersetzen Sie die anderen <...>-Werte sowie {serviceId} durch die in den jeweiligen Schritten zurückgegebenen Werte.

Tarif und Rechenzentrum wählen

Listen Sie die Bare-Metal-Tarife auf:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/plans \
  --header 'Authorization: Bearer <api-key>'

Die Liste ist paginiert, mit 25 Tarifen pro Seite, sofern pageSize nicht mehr anfordert, maximal 1000. Jeder Tarif in data enthält id und slug, seine Hardware unter specs und zwei für die Bestellung entscheidende Felder:

• availability enthält einen Eintrag pro Rechenzentrum mit dessen code (etwa ams1), city und facility sowie dem dort verfügbaren Bestand quantity.
• pricing enthält die currency und unter rates einen Eintrag für jeden angebotenen Abrechnungszyklus. priceMillicents ist der Preis einer Periode dieses Zyklus und effectiveMonthlyMillicents derselbe Preis pro Monat, beide in Tausendstel Cent (Geldbeträge).

Wählen Sie einen Tarif und ein Rechenzentrum mit quantity größer null und merken Sie sich den slug des Tarifs sowie den code des Rechenzentrums. Um stattdessen vom Standort auszugehen, nennt Regionen auflisten jedes bestellbare Rechenzentrum mit code, Stadt und Einrichtung.

Server bestellen

Erstellen Sie eine Bestellung für diesen Tarif im gewählten Rechenzentrum mit dem gewünschten Abrechnungszyklus:

curl --request POST \
  --url https://api.serverside.com/v1/billing/orders \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cycle": "MONTHLY",
  "items": [
    {
      "type": "BAREMETAL",
      "plan": "<plan-slug>",
      "datacenter": "<datacenter-code>",
      "name": "<hostname>"
    }
  ]
}
'

plan und datacenter akzeptieren neben Slug und Code auch IDs. name ist optional, umfasst 2 bis 64 Zeichen und wird bei der Bereitstellung zum Hostnamen des Betriebssystems; ein Name wie web1.example.com setzt somit beides.

cycle ist erforderlich und akzeptiert HOURLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY oder ANNUALLY. Der weitere Ablauf hängt von Ihrer Wahl ab:

• Eine Laufzeit (MONTHLY bis ANNUALLY): Die Bestellung wird mit einer Rechnung gespeichert, noch ohne Bereitstellung. Die Antwort ist 201; bewahren Sie data.order.id und data.invoiceId für den nächsten Schritt auf.
• HOURLY: Der Server wird innerhalb der Anfrage bereitgestellt, ohne Rechnungserstellung. data.provisionedItems[0].provisionedId ist die Server-ID, die {serviceId} der letzten beiden Schritte. Springen Sie daher zur Betriebssystemwahl. Stündliche Abrechnung erfordert, dass billing.isUsageBased bei Berechtigte Funktionen abrufen true ist. Neue Organisationen haben dies nicht; derzeit erfolgt die Freischaltung auf Anfrage über den Support in der Cloud-Konsole. Ohne sie antwortet die Bestellung mit 422 USAGE_BILLING_DISABLED.

Der Server erhält ein IPv4-/30 und ein IPv6-/120, beide im Tarifpreis enthalten; IPv6 entfällt, wenn das Rechenzentrum keinen IPv6-Adressraum vergeben kann. Abrechnung beschreibt größere IPv4-Präfixe und das Weglassen einer Adressfamilie.

Der Header Idempotency-Key ist optional. Erzeugen Sie einen Wert pro Bestellung und senden Sie bei einer Wiederholung nach Zeitüberschreitung denselben Wert, damit die erste Bestellung zurückgegeben wird, statt eine zweite aufzugeben; Idempotenz erklärt die Regeln.

Rechnung bezahlen

Ein Server mit Laufzeit wird nach vollständiger Bezahlung seiner Rechnung bereitgestellt; keine Zahlung einer Bestellrechnung erfolgt automatisch. Eine unbezahlte Bestellung wird innerhalb von 24 Stunden storniert. Ein Skript kann sie über Rechnung bezahlen aus Kontoguthaben begleichen:

curl --request POST \
  --url https://api.serverside.com/v1/billing/invoices/{invoiceId}/pay \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "providerType": "ACCOUNT_CREDIT"
}
'

Die Zahlung verwendet das verfügbare Guthaben bis zum offenen Betrag und zeigt status SUCCEEDED. Reicht das Guthaben nicht aus, bleibt ein Teil der Rechnung offen und der Server wartet auf den Rest. Rufen Sie die Rechnung ab und lesen Sie amountDue in Cent. Ohne Guthaben antwortet der Aufruf mit 422 PAYMENT_FAILED.

providerType STRIPE mit der ID einer gespeicherten Karte in methodId belastet stattdessen diese Karte. Die API listet gespeicherte Karten nur in den Organisationseinstellungen auf, die eine Konsolensitzung erfordern. Ein Schlüssel hat daher keinen Aufruf zum Ermitteln der ID. Ohne methodId startet STRIPE eine Zahlung, die im Browser bestätigt werden muss (Abrechnung).

Rufen Sie dann die Bestellung etwa alle 20 Sekunden ab, bis ihr Posten in items den status COMPLETED hat:

curl --request GET \
  --url https://api.serverside.com/v1/billing/orders/{orderId} \
  --header 'Authorization: Bearer <api-key>'

Die Bestellung selbst zeigt bis zur Bereitstellung UNPAID, danach COMPLETE. Die provisionedId des Postens ist die neue Server-ID, die {serviceId} aller späteren Aufrufe. Ein Posten mit FAILED wird nicht von selbst bereitgestellt: Auch die Bestellung zeigt FAILED, und der Support benötigt deren id, um sie abzuschließen.

Betriebssystem wählen

Listen Sie die Images auf, die zum neuen Server passen:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/deploy/images \
  --header 'Authorization: Bearer <api-key>'

Jedes Image hat id, name, einen slug wie ubuntu-24.04, eine platform (LINUX oder WINDOWS), den erstellten defaultUser und die unterstützten raidVariants.

Bereitstellen

Starten Sie die Bereitstellung. image akzeptiert die id oder den slug des Images; sshKeyIds akzeptiert IDs aus SSH-Schlüssel auflisten.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/deploy \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "<image-id>",
  "sshKeyIds": [
    "<ssh-key-id>"
  ],
  "raidVariant": "RAID1"
}
'

Eine Linux-Bereitstellung benötigt eine Anmeldemöglichkeit: SSH-Schlüssel, password oder eigenes cloudInit. Windows benötigt ein password. username verwendet standardmäßig den defaultUser des Images. Unter Linux gelten username und password zusätzlich zu den Schlüsseln; ein dort benannter Benutzer erhält passwortloses sudo. raidVariant ist standardmäßig NONE; jeder andere Wert muss vom Image aufgeführt werden.

Die Antwort ist 201 mit dem nun laufenden Vorgang vom type DEPLOYMENT. Verfolgen Sie ihn über Dienststatus abrufen:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/status \
  --header 'Authorization: Bearer <api-key>'

operation enthält die laufende Bereitstellung mit progress und lastProgressMessage; nach Abschluss zeigt lastOperation.state COMPLETED oder FAILED. Eine Bereitstellung startet nur im Dienst-state ACTIVE. Läuft noch ein anderer Vorgang, antwortet die API mit 409 und dem Code OPERATION_IN_PROGRESS. Sobald COMPLETED erscheint, melden Sie sich an der von Bare-Metal-Dienst abrufen zurückgegebenen primaryIpv4 an.