API-snelstart

Een API-sleutel maken

Open in de cloudconsole de organisatie-instellingen en kies Create an API Key onder Manage API Keys. De console toont de sleutel één keer bij het maken; kopieer hem voordat u het dialoogvenster sluit.

Elke aanvraag in de documentatie toont deze als <api-key> in de Authorization: Bearer-header. Vul daar uw sleutel in en vervang de overige <...>-waarden en {serviceId} door de waarden die elke stap teruggeeft.

Een configuratie en datacenter kiezen

Vraag de dedicated-serverconfiguraties op:

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

De lijst is gepagineerd met 25 configuraties per pagina, tenzij pageSize er meer vraagt, tot maximaal 1000. Elke configuratie in data bevat id en slug, hardware onder specs en twee velden die de bestelling bepalen:

• availability bevat een vermelding per datacenter met de code (zoals ams1), city, facility en de beschikbare quantity.
• pricing geeft de currency en onder rates een vermelding per aangeboden factureringscyclus. De priceMillicents van een vermelding is de prijs van één periode; effectiveMonthlyMillicents is dezelfde prijs per maand, beide in duizendsten van een cent (Geld).

Kies een configuratie en datacenter met quantity boven nul en bewaar de slug van de configuratie en de code van het datacenter. Wilt u bij een locatie beginnen, dan noemt Regio's opvragen elk datacenter waar u kunt bestellen met code, stad en faciliteit.

De server bestellen

Maak een bestelling voor de configuratie in dat datacenter met de gewenste factureringscyclus:

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 en datacenter accepteren naast slug en code ook ID's. name is optioneel, telt 2 tot 64 tekens en wordt bij de implementatie de hostnaam van het besturingssysteem. Een naam zoals web1.example.com stelt dus beide in.

cycle is verplicht en accepteert HOURLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY of ANNUALLY. Het vervolg hangt van uw keuze af:

• Een looptijd (MONTHLY tot ANNUALLY): de bestelling wordt met een factuur opgeslagen; er wordt nog niets ingericht. Het antwoord is 201; bewaar data.order.id en data.invoiceId voor de volgende stap.
• HOURLY: de server wordt tijdens de aanvraag ingericht zonder factuur. data.provisionedItems[0].provisionedId is de server-ID, de {serviceId} van de laatste twee stappen. Ga daarom direct naar de keuze van het besturingssysteem. Uurfacturering vereist billing.isUsageBased true bij Beschikbare rechten opvragen. Een nieuwe organisatie heeft dit niet; momenteel wordt het op verzoek toegekend via support in de cloudconsole. Zonder dit recht antwoordt de bestelling met 422 USAGE_BILLING_DISABLED.

De server krijgt een IPv4-/30 en IPv6-/120, beide inbegrepen in de configuratieprijs. IPv6 wordt weggelaten wanneer het datacenter geen IPv6-ruimte kan toewijzen. Facturering beschrijft een groter IPv4-prefix en het weglaten van een adresfamilie.

De Idempotency-Key-header is optioneel. Genereer één waarde per bestelling en verstuur bij herhaling na een time-out dezelfde waarde, zodat de eerste bestelling wordt teruggegeven in plaats van een tweede te plaatsen; Idempotentie bevat de regels.

De factuur betalen

Een server met een looptijd wordt ingericht zodra de factuur volledig betaald is. De bestelfactuur wordt nooit automatisch betaald. Een onbetaalde bestelling wordt binnen 24 uur geannuleerd. Vanuit een script rekent Factuur betalen af met accounttegoed:

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"
}
'

De betaling gebruikt het beschikbare tegoed tot het verschuldigde bedrag en toont status SUCCEEDED. Bij onvoldoende saldo blijft een deel open en wacht de server op het restant. Vraag de factuur op en lees amountDue in centen. Zonder enig tegoed antwoordt de aanroep met 422 PAYMENT_FAILED.

providerType STRIPE met de ID van een opgeslagen kaart in methodId belast die kaart. De API vermeldt opgeslagen kaarten alleen bij de organisatie-instellingen, die een consolesessie vereisen. Een sleutel heeft dus geen aanroep om de ID te vinden. Zonder methodId start STRIPE een betaling die in een browser moet worden bevestigd (Facturering).

Vraag daarna de bestelling op, ongeveer elke 20 seconden, totdat het item in items status COMPLETED toont:

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

De bestelling zelf toont UNPAID totdat de inrichting is uitgevoerd en daarna COMPLETE. De provisionedId van het item is de nieuwe server-ID, de {serviceId} voor alle volgende aanroepen. Een item met FAILED wordt niet vanzelf ingericht: ook de bestelling toont FAILED, en support heeft de id van de bestelling nodig om deze af te ronden.

Een besturingssysteem kiezen

Vraag de images op die bij de nieuwe server passen:

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

Elk image heeft een id, name, een slug zoals ubuntu-24.04, een platform (LINUX of WINDOWS), de aangemaakte defaultUser en ondersteunde raidVariants.

Implementeren

Start de implementatie. image accepteert de id of slug van het image; sshKeyIds accepteert ID's uit SSH-sleutels opvragen.

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"
}
'

Een Linux-implementatie heeft een aanmeldmethode nodig: een SSH-sleutel, password of eigen cloudInit. Windows vereist een password. username gebruikt standaard de defaultUser van het image. Onder Linux gelden username en password naast de sleutels; een genoemde gebruiker krijgt sudo zonder wachtwoord. raidVariant is standaard NONE; elke andere waarde moet door het image worden vermeld.

Het antwoord is 201 met de nu lopende bewerking van type DEPLOYMENT. Volg deze met Dienststatus opvragen:

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

operation bevat de lopende implementatie met progress en lastProgressMessage; na afloop toont lastOperation.state COMPLETED of FAILED. Een implementatie start alleen wanneer de state van de dienst ACTIVE is. Loopt er nog een andere bewerking, dan antwoordt de API met 409 en code OPERATION_IN_PROGRESS. Zodra COMPLETED verschijnt, meldt u zich aan op de primaryIpv4 die Dedicated server opvragen teruggeeft.