API-Konventionen

Basis-URL und Versionen

https://api.serverside.com

Jeder Pfad beginnt mit dem Versionssegment /v1. Anfragen und Antworten sind JSON über HTTPS; senden Sie bei Anfragen mit Body Content-Type: application/json. Jede Antwort enthält einen Header X-Request-Id.

Namen und Werte

Ein Feld mit fester Wertemenge führt diese unter Allowed values auf seiner Endpunktseite auf. Alle Mengen verwenden Großbuchstaben außer location eines Fehlerdetails, das nur in Fehlerantworten erscheint. Die API vergleicht ohne Beachtung der Groß-/Kleinschreibung, daher wird semi_annually als SEMI_ANNUALLY gelesen. Andere Schreibweisen (SemiAnnually), Zahlen statt Namen oder kommaseparierte Listen werden mit 400 abgelehnt; der Fehler nennt die erlaubten Werte. Einzige Ausnahme ist der type eines Bestellpostens, der exakt BAREMETAL oder IP_BLOCK lauten muss.

IDs sind UUIDs; ein Feld ohne ID ist null, nie eine leere Zeichenfolge. Manche ID-Felder akzeptieren auch einen unveränderlichen Namen: den slug eines Bare-Metal-Tarifs (epyc-9354p) und den code eines Rechenzentrums, drei Buchstaben für die Metropolregion und eine Standortnummer (ams1). Wahrheitsfelder beginnen als Frage mit is, etwa isLocked; Felder mit Einheit nennen diese: speedMbps, memoryGb, sizeBytes. Gesendete Zeitdauern sind in Sekunden.

IP-Adressen und Netzwerke werden als Zeichenfolgen wie "192.0.2.10" und "192.0.2.0/28" übertragen. IPv4 muss in üblicher Punktschreibweise stehen; 10.1 und 010.0.0.1 werden abgelehnt. IPv6 darf jede Schreibweise verwenden, jedoch ohne Klammern oder Zone. Zeitstempel sind ISO-8601-Zeichenfolgen. Gesendete müssen einen Offset enthalten: 2026-09-20T00:00:00Z und 2026-09-20T02:00:00+02:00 bezeichnen denselben Zeitpunkt; 2026-09-20T00:00:00 wird abgelehnt. Alle von der API gesendeten Zeitstempel sind in UTC und enden auf Z.

Anfragebodys

Eine vom Endpunkt nicht deklarierte JSON-Eigenschaft wird mit 400 VALIDATION_ERROR abgelehnt; das Detail INVALID_BODY nennt sie. So werden auch falsch geschriebene optionale Felder erkannt, statt verworfen.

PATCH ändert nur im Body genannte Felder: Ausgelassene behalten ihren Wert; die Antwort ist 200 mit der Ressource wie bei ihrem GET. Die drei PATCH-Vorgänge für Server, virtuelles Netzwerk und SSH-Schlüssel akzeptieren ein Feld, name; ein null-Name lässt ihn unverändert. PUT ersetzt eine Einstellung vollständig, etwa Startmodus oder iPXE-Skript; auch lock und unlock sind ein PUT-Paar.

Geldbeträge

Beträge sind ganze Zahlen in der als currency angegebenen Datensatzwährung (pricing.currency bei Tarifen). Ganze Zahlen halten jeden Betrag exakt. Die meisten JSON-Parser lesen Dezimalwerte wie 0.10 als binäre Gleitkommazahlen, die sie nicht exakt darstellen können: In JavaScript ist 0.1 + 0.2 gleich 0.30000000000000004. Der Feldname bestimmt die Skalierung:

• Ein auf Millicents endender Feldname zählt Tausendstel Cent: 150000 entspricht 1,50. Preise und Raten auf Tarifen, Bestellungen und Abonnements werden so geschrieben, damit Stundenpreise Centbruchteile behalten.
• Alle anderen Geldfelder zählen Cent: 12999 entspricht 129,99. Dies gilt für Rechnungen, Zahlungen, Nutzungsgebühren und Kontoguthaben.

Eine Bestellung enthält nur ihren Preis. Steuern, Rabatte und offener Betrag stehen auf der Rechnung (Abrechnung).

Erfolgs- und Fehlerantworten

Der HTTP-Status unterscheidet die beiden Formate: Eine 2xx-Antwort ist erfolgreich, alles andere ein Fehler; success wiederholt dies im Body.

Erfolg

{
  "success": true,
  "data": { },
  "pagination": {
    "totalRecords": 42,
    "page": 1,
    "pageSize": 25,
    "totalPages": 2
  }
}

Ein erstellender Aufruf antwortet mit 201 und dem erstellten Objekt im Format eines Lesezugriffs. 202 Accepted bedeutet, dass die Änderung noch angewendet wird. Verbinden und Trennen eines Servers mit einem virtuellen Netzwerk sowie Startmoduswechsel geben den Fortschritt in data aus: status APPLYING und since, die Annahmezeit. Eine Serverlöschung antwortet während des Abbaus mit 202 ohne Body. 204 No Content hat überhaupt keinen Body. Rechnungs-PDF herunterladen ist der einzige Endpunkt, der eine Datei statt JSON liefert.

Fehler

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "pageSize: Must be between 1 and 1000.",
  "traceId": "SRV-7F3A-0C21-9B4E-51D2",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Must be between 1 and 1000.",
      "field": "pageSize",
      "location": "query"
    }
  ]
}

Fehlerbodys teilen success und data mit Erfolgen, sodass ein Client beide mit einem Typ lesen kann.

Paginierung

Acht Listen liefern alle Zeilen zugleich ohne pagination: Regionen auflisten, Betriebssystemimages auflisten, Anwendungen auflisten, Netzteilzustand abrufen, Konsolensitzungen auflisten, Virtuelle Medien auflisten, Sicherheitsscan abrufen und Scan-Plugins auflisten. Alle anderen Listen sind paginiert und akzeptieren dieselben Parameter:

pagination der Antwort wiederholt page und pageSize und ergänzt totalRecords und totalPages. Fragen Sie für eine vollständige Liste Seiten ab, bis page totalPages erreicht; eine leere Liste liefert totalPages 0, was zuerst zu prüfen ist. Auch das Stoppen bei der ersten leeren Seite funktioniert. Jede paginierte Liste beendet die Sortierung mit der Zeilen-ID; bei gleichem sortColumn bleibt die Reihenfolge über Seiten hinweg stabil.

curl --request GET \
  --url 'https://api.serverside.com/v1/baremetal?page=2&pageSize=100&sortColumn=name' \
  --header 'Authorization: Bearer <api-key>'

Ein Textfeldfilter findet jeden Wert, der den Text ohne Beachtung der Groß-/Kleinschreibung enthält. Ein Filter auf ein Feld mit erlaubten Werten verwendet die API-Schreibweise, etwa filter[status]=CANCELLATION_REQUESTED; ein Wahrheitsfilter true oder false. Unzulässige Werte, nicht filterbare Feldnamen und jegliche Filter bei Listen ohne Filterunterstützung werden mit 400 VALIDATION_ERROR und einem Detail INVALID_VALUE abgelehnt. Dessen field ist der gesendete Schlüssel (filter[status]). Ein leerer Wert ist kein Filter.

sortColumn und die Namen in filter[...] gehören nicht zum stabilen Vertrag. Ein unbekanntes sortColumn wird ignoriert; die Liste erscheint in ihrer Standardsortierung.

Fehler

Statuscodes

Retry-After ist eine Sekundenanzahl. Jede 503 und jede selbständig vorübergehende 409, etwa bei Controller-Neustart, enthält sie. Lesezugriffe nach 500, 502 oder 504 können sicher wiederholt werden. Bei ändernden Aufrufen akzeptieren nur die fünf unter Idempotenz genannten einen sicher wiederholbaren Schlüssel. Lesen Sie vor Wiederholung aller anderen den vorhandenen Zustand, da die erste Anfrage erfolgreich gewesen sein kann.

Validierung

Zwei Codes enthalten eine Liste von details:

• VALIDATION_ERROR, 400: Die Anfrage konnte nicht gelesen werden. Der Detail-code ist INVALID_BODY, wenn der JSON-Body selbst unlesbar ist: Syntaxfehler, falscher Typ, fehlendes Pflichtmitglied, nicht deklarierte Eigenschaft oder Wert außerhalb erlaubter Feldwerte. INVALID_VALUE gilt für Abfrage-, Routen- oder Headerwerte sowie gelesene Bodyfelder, die deklarierte Längen- oder Bereichsgrenzen verletzen. VALUE_OUT_OF_RANGE markiert eine im Vorgangscode geprüfte Zahl.
• VALIDATION_FAILED, 422: Die Anfrage wurde gelesen, aber von einer oder mehreren Regeln abgelehnt. Jeder Detail-code nennt die Regel, etwa BILLING_CYCLE_UNAVAILABLE bei Bestellungen; seine location ist null.

Bodyfelder werden anhand ihres JSON-Pfads mit Arrayindizes benannt (items[0].plan, billingAddress.countryCode). Abfragefelder heißen wie gesendet, Routenfelder wie ihr Parameter, Header wie ihr Name. Bei einem Detail lautet message field: problem; bei mehreren The request has N problems: gefolgt von jedem Problem.

Eine Bestellung mit einem für ihren Tarif nicht angebotenen Abrechnungszyklus:

{
  "success": false,
  "data": null,
  "code": "VALIDATION_FAILED",
  "message": "cycle: This billing cycle is not offered.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "BILLING_CYCLE_UNAVAILABLE",
      "message": "This billing cycle is not offered.",
      "field": "cycle",
      "location": null
    }
  ]
}

Eine nicht passende ID im Body wird nach ihrem Ziel behandelt. Tarif, Image, Anwendung, Segment oder Schnittstelle sind Katalogeinträge; unbekannte ergeben 422 mit einem Detail am Feld, etwa OFFERING_NOT_FOUND für items[0].plan. Die ID eines Objekts Ihrer Organisation (Server, Netzwerk, SSH-Schlüssel) ergibt 404 ENTITY_NOT_FOUND ohne Feld; fremde IDs sehen daher wie nicht vorhandene aus. Ausnahme Rechenzentrum: unbekannter code ergibt ein Detail DATACENTER_NOT_FOUND, unbekannte UUID 422 OFFERING_NOT_AVAILABLE.

Codes

Codes, die jeder Endpunkt liefern kann:

Codes für Bare-Metal-Server:

Codes für Bestellungen und Abrechnung:

Netzwerkcodes stehen bei den jeweiligen Aufrufen in IP-Adressen verwalten und Virtuelle Netzwerke einrichten. Detailcodes von VALIDATION_FAILED nennt die Anleitung des betreffenden Vorgangs.

Idempotenz

Fünf Vorgänge akzeptieren einen Header Idempotency-Key mit bis zu 200 Zeichen: Bestellung erstellen, Bare-Metal-Dienst erstellen, IP-Block erstellen sowie Server mit einem virtuellen Netzwerk verbinden oder davon trennen. Senden Sie pro neuer Aktion einen neuen Wert und bei Wiederholung derselben Aktion denselben.

Die drei Erstellungsaufrufe teilen eine Schlüsselmenge pro Organisation; ein Schlüssel wird nie vergessen. Eine Wiederholung mit gleichem Schlüssel und gleichem Kauf (Abrechnungszyklus, Aktionscode und Posten) erstellt nichts Neues und antwortet statt 201 mit 200 und dem ursprünglich Erstellten. Bestellung erstellen setzt zudem data.isReplayed auf true. Tarif-slug in einer Anfrage und Tarif-ID in der anderen gelten weiterhin als derselbe Kauf, ebenso Rechenzentrums-code und ID. Derselbe Schlüssel mit anderem Kauf wird mit 409 IDEMPOTENCY_KEY_REUSED abgelehnt. Läuft die erste Anfrage noch, erhält eine Wiederholung 409 ORDER_CREATION_IN_PROGRESS oder ORDER_PROVISIONING_IN_PROGRESS mit Retry-After: 5; senden Sie nach diesen Sekunden erneut.

Bei virtuellen Netzwerkaufrufen gehört ein Schlüssel zum Server und bleibt bis 90 Tage nach Umsetzung der Änderung gespeichert. Eine Wiederholung antwortet erneut mit 202, ohne eine zweite Änderung einzureihen; derselbe Schlüssel mit anderem Netzwerk oder Segment erhält 409 IDEMPOTENCY_KEY_REUSED. Eine zweite Änderung während der Umsetzung der ersten erhält 409 NETWORK_CHANGE_IN_PROGRESS mit Retry-After: 10.

Ratenlimits

Jeder API-Schlüssel hat eigene Limits:

Die Limits werden vor der API durchgesetzt; die API selbst sendet keine 429.

Das Abfragen einer Bereitstellung alle 20 Sekunden wie in den Anleitungen benötigt 3 Lesezugriffe pro Minute.