API-conventies

Basis-URL en versies

https://api.serverside.com

Elk pad begint met een versiesegment, /v1. Aanvragen en antwoorden zijn JSON via HTTPS; stuur Content-Type: application/json bij elke aanvraag met een body. Elk antwoord bevat een X-Request-Id-header.

Namen en waarden

Een veld met vaste waarden vermeldt deze onder Allowed values op de endpointpagina. Alle verzamelingen gebruiken hoofdletters, behalve location van een foutdetail, dat alleen in foutantwoorden voorkomt. De API vergelijkt hoofdletterongevoelig: semi_annually wordt dus gelezen als SEMI_ANNUALLY. Andere spelling (SemiAnnually), een getal in plaats van de naam of een kommagescheiden lijst wordt geweigerd met 400; de fout noemt de toegestane waarden. De enige uitzondering is het type van een bestelitem, dat exact BAREMETAL of IP_BLOCK moet zijn.

ID's zijn UUID's; een veld zonder ID is null, nooit een lege tekenreeks. Sommige ID-velden accepteren ook een onveranderlijke naam: de slug van een dedicated-serverconfiguratie (epyc-9354p) en de code van een datacenter, drie letters voor de stedelijke regio plus een locatienummer (ams1). Waar/onwaar-velden beginnen als vraag met is, zoals isLocked; velden met een eenheid noemen die: speedMbps, memoryGb, sizeBytes. Een verstuurde duur is in seconden.

IP-adressen en netwerken worden als tekenreeksen verstuurd, zoals "192.0.2.10" en "192.0.2.0/28". IPv4 moet in de gebruikelijke puntnotatie staan; 10.1 en 010.0.0.1 worden geweigerd. IPv6 mag elke notatie gebruiken, maar zonder haken of zone. Tijdstempels zijn ISO 8601-tekenreeksen. Een verstuurde tijdstempel moet een offset bevatten: 2026-09-20T00:00:00Z en 2026-09-20T02:00:00+02:00 zijn hetzelfde moment; 2026-09-20T00:00:00 wordt geweigerd. Elke tijdstempel van de API is UTC en eindigt op Z.

Aanvraagbody's

Een niet door het endpoint gedeclareerde JSON-eigenschap wordt geweigerd met 400 VALIDATION_ERROR; het detail INVALID_BODY noemt die eigenschap. Zo wordt een verkeerd gespeld optioneel veld opgemerkt in plaats van genegeerd.

PATCH wijzigt alleen wat de body noemt: weggelaten velden behouden hun waarde, en het antwoord is 200 met de resource zoals GET die teruggeeft. De drie PATCH-bewerkingen voor server, virtueel netwerk en SSH-sleutel accepteren één veld, name; een null-naam laat de naam ongewijzigd. PUT vervangt één hele instelling, zoals opstartmodus of iPXE-script; ook lock en unlock zijn een PUT-paar.

Geld

Bedragen zijn gehele getallen in de valuta van hun record, vermeld als currency (pricing.currency bij configuraties). Gehele getallen houden elk bedrag exact. De meeste JSON-parsers lezen decimalen zoals 0.10 als binaire drijvendekommagetallen, die deze niet exact kunnen opslaan: in JavaScript is 0.1 + 0.2 gelijk aan 0.30000000000000004. De veldnaam geeft de schaal:

• Een naam die eindigt op Millicents telt duizendsten van een cent: 150000 is 1,50. Prijzen en tarieven op configuraties, bestellingen en abonnementen worden zo geschreven, zodat uurtarieven centfracties behouden.
• Alle andere geldvelden tellen centen: 12999 is 129,99. Dit geldt voor facturen, betalingen, gebruikskosten en accounttegoed.

Een bestelling bevat alleen de prijs. Belasting, kortingen en het verschuldigde bedrag staan op de factuur (Facturering).

Succes- en foutantwoorden

De HTTP-status onderscheidt de twee formaten: 2xx is succes, alles daarbuiten een fout; success herhaalt dat in de body.

Succes

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

Een aanroep die iets maakt antwoordt met 201 en het gemaakte object in het formaat van een leesaanvraag. 202 Accepted betekent dat de wijziging nog wordt toegepast. Aansluiten en loskoppelen van een server op een virtueel netwerk en wisselen van opstartmodus geven de voortgang in data: status APPLYING en since, het moment van acceptatie. Verwijderen van een server antwoordt met 202 zonder body tijdens afbraak. 204 No Content heeft helemaal geen body. Factuur-pdf downloaden is het enige endpoint dat een bestand teruggeeft in plaats van JSON.

Fout

{
  "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"
    }
  ]
}

Foutbody's delen success en data met succesantwoorden; een client kan beide met één type lezen.

Paginering

Acht lijsten geven alle regels tegelijk zonder pagination: Regio's opvragen, OS-images opvragen, Applicaties opvragen, Voedingsgezondheid opvragen, Consolesessies opvragen, Virtuele media opvragen, Beveiligingsscan opvragen en Scanplugins opvragen. Elke andere lijst is gepagineerd en gebruikt dezelfde parameters:

pagination herhaalt page en pageSize en voegt totalRecords en totalPages toe. Vraag voor een hele lijst pagina's op totdat page totalPages bereikt. Een lege lijst antwoordt met totalPages 0; controleer dat eerst. Stoppen bij de eerste lege pagina werkt ook. Elke gepagineerde lijst sorteert als laatste op de regel-ID, zodat regels met dezelfde sortColumn hun volgorde tussen pagina's behouden.

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

Een tekstfilter vindt elke waarde die de tekst hoofdletterongevoelig bevat. Een filter op een veld met toegestane waarden gebruikt de API-schrijfwijze, filter[status]=CANCELLATION_REQUESTED; een waar/onwaar-filter accepteert true of false. Ongeldige waarden, niet-filterbare namen en alle filters op lijsten zonder filterondersteuning worden geweigerd met 400 VALIDATION_ERROR en detail INVALID_VALUE. De field daarvan is de verstuurde sleutel (filter[status]). Een lege waarde betekent geen filter.

sortColumn en namen binnen filter[...] horen niet bij het stabiele contract. Een onbekende sortColumn wordt genegeerd; de lijst komt in standaardvolgorde terug.

Fouten

Statussen

Retry-After is een aantal seconden. Elke 503 bevat dit, evenals elke 409 die vanzelf oplost, zoals een herstartende beheercontroller. Leesaanvragen herhalen na 500, 502 of 504 is veilig. Van wijzigende aanroepen accepteren alleen de vijf onder Idempotentie een sleutel die herhalen veilig maakt. Lees voor elke andere herhaling wat er bestaat, want de eerste aanvraag kan zijn uitgevoerd.

Validatie

Twee codes bevatten een lijst details:

• VALIDATION_ERROR, 400: de aanvraag kon niet worden gelezen. Detail-code is INVALID_BODY wanneer de JSON-body zelf onleesbaar is: syntaxisfout, verkeerd type, ontbrekend verplicht lid, niet-gedeclareerd lid of waarde buiten toegestane veldwaarden. INVALID_VALUE geldt voor query-, route- of headerwaarden en voor gelezen bodyvelden die een gedeclareerde lengte- of bereiklimiet schenden. VALUE_OUT_OF_RANGE markeert een getal dat de bewerking zelf controleert.
• VALIDATION_FAILED, 422: de aanvraag is gelezen en door één of meer regels geweigerd. Elke detail-code noemt de regel, zoals BILLING_CYCLE_UNAVAILABLE bij een bestelling; location is null.

Een bodyveld wordt genoemd met JSON-pad en array-indexen (items[0].plan, billingAddress.countryCode). Een queryveld heet zoals verstuurd, een routeveld naar de parameter en een header naar de headernaam. Bij één detail luidt message field: problem; bij meerdere The request has N problems: gevolgd door elk probleem.

Een bestelling met een factureringscyclus die de configuratie niet aanbiedt:

{
  "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
    }
  ]
}

Een onbekende ID in de body wordt behandeld naar wat deze noemt. Configuratie, image, applicatie, segment of interface zijn catalogusitems; onbekende leveren 422 met een velddetail, zoals OFFERING_NOT_FOUND op items[0].plan. De ID van iets dat uw organisatie bezit (server, netwerk, SSH-sleutel) geeft 404 ENTITY_NOT_FOUND zonder veld. Een ID van een andere organisatie ziet er zo hetzelfde uit als een niet-bestaande. Een datacenter is de uitzondering: onbekende code geeft detail DATACENTER_NOT_FOUND, onbekende UUID geeft 422 OFFERING_NOT_AVAILABLE.

Codes

Codes die elk endpoint kan teruggeven:

Codes voor dedicated servers:

Codes voor bestellingen en facturering:

Netwerkcodes staan bij hun aanroepen in IP-adressen beheren en Virtuele netwerken instellen. Detailcodes van VALIDATION_FAILED worden genoemd in de handleiding van de betreffende bewerking.

Idempotentie

Vijf bewerkingen accepteren een Idempotency-Key-header van maximaal 200 tekens: een bestelling maken, een dedicated server maken, een IP-blok maken en een server op een virtueel netwerk aansluiten of loskoppelen. Verstuur een nieuwe waarde voor elke nieuwe actie en dezelfde waarde bij herhaling van die actie.

De drie aanmaakaanroepen delen één sleutelverzameling per organisatie; een sleutel wordt nooit vergeten. Een herhaling met dezelfde sleutel en dezelfde aankoop (factureringscyclus, promotiecode en items) plaatst niets nieuws en antwoordt met 200 in plaats van 201 en wat de eerste aanvraag maakte. Bestelling maken zet ook data.isReplayed op true. Een configuratie in de ene aanvraag met slug noemen en in de andere met ID geldt nog als dezelfde aankoop, net als datacenter-code en ID. Dezelfde sleutel met een andere aankoop wordt geweigerd met 409 IDEMPOTENCY_KEY_REUSED. Loopt de eerste aanvraag nog, dan krijgt een herhaling 409 ORDER_CREATION_IN_PROGRESS of ORDER_PROVISIONING_IN_PROGRESS met Retry-After: 5; probeer na dat aantal seconden opnieuw.

Bij virtuele-netwerkaanroepen hoort een sleutel bij de server en blijft deze bewaard tot 90 dagen na toepassing. Een herhaling antwoordt weer met 202 zonder een tweede wijziging in te plannen; dezelfde sleutel met een ander netwerk of segment krijgt 409 IDEMPOTENCY_KEY_REUSED. Een tweede wijziging terwijl de eerste wordt toegepast krijgt 409 NETWORK_CHANGE_IN_PROGRESS met Retry-After: 10.

Aanvraaglimieten

Elke API-sleutel heeft eigen limieten:

De limieten worden vóór de API afgedwongen; de API zelf verstuurt geen 429.

Een implementatie elke 20 seconden opvragen, zoals in de handleidingen, gebruikt 3 leesaanvragen per minuut.