Démarrage rapide API

Créer une clé API

Dans la console cloud, ouvrez les paramètres de votre organisation et choisissez Create an API Key sous Manage API Keys. La console n’affiche la clé qu’à sa création ; copiez-la avant de fermer la boîte de dialogue.

Chaque requête de la documentation la représente par <api-key> dans l’en-tête Authorization: Bearer. Remplacez-la par votre clé, et les autres valeurs <...> ainsi que {serviceId} par celles renvoyées à chaque étape.

Choisir une offre et un datacenter

Listez les offres bare metal :

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

La liste est paginée, avec 25 offres par page, sauf si pageSize en demande davantage, jusqu’à 1000. Chaque offre dans data porte son id, son slug, son matériel sous specs et deux champs qui déterminent la commande :

• availability contient une entrée par datacenter avec son code (comme ams1), sa city, sa facility et la quantity en stock.
• pricing indique la currency et, sous rates, une entrée par cycle de facturation proposé. priceMillicents est le prix d’une période du cycle et effectiveMonthlyMillicents son équivalent mensuel, tous deux en millièmes de centime (Montants).

Choisissez une offre et un datacenter dont la quantity est supérieure à zéro ; conservez le slug de l’offre et le code du datacenter. Pour commencer par un emplacement, Lister les régions donne chaque datacenter où commander, avec son code, sa ville et son installation.

Commander le serveur

Créez une commande pour l’offre dans ce datacenter, avec le cycle de facturation souhaité :

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 et datacenter acceptent les ID ainsi que le slug et le code. name est facultatif, de 2 à 64 caractères ; le déploiement en fait le nom d’hôte du système, donc un nom comme web1.example.com définit les deux.

cycle est obligatoire et accepte HOURLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY ou ANNUALLY. La suite dépend du choix :

• Une période (MONTHLY à ANNUALLY) : la commande est enregistrée avec une facture, sans provisionnement immédiat. La réponse est 201 ; conservez data.order.id et data.invoiceId pour l’étape suivante.
• HOURLY : le serveur est provisionné pendant la requête, sans facture. data.provisionedItems[0].provisionedId est son ID, le {serviceId} des deux dernières étapes ; passez donc au choix du système. La facturation horaire exige billing.isUsageBased à true dans Obtenir les droits, ce qu’une nouvelle organisation ne possède pas. Elle est actuellement accordée sur demande au support dans la console cloud ; sans elle, la commande répond 422 USAGE_BILLING_DISABLED.

Le serveur reçoit un /30 IPv4 et un /120 IPv6, inclus dans le prix de l’offre ; IPv6 est omis si le datacenter n’a pas d’espace IPv6 disponible. La facturation explique le choix d’un préfixe IPv4 plus grand et l’omission d’une famille.

L’en-tête Idempotency-Key est facultatif. Générez une valeur par commande et renvoyez la même après un délai dépassé, afin que la nouvelle tentative retourne la commande initiale au lieu d’en passer une seconde ; les règles figurent sous Idempotence.

Payer la facture

Un serveur commandé par période est provisionné une fois sa facture intégralement payée ; rien ne paie automatiquement la facture d’une commande. Une commande impayée est annulée dans les 24 heures. Depuis un script, Payer une facture la règle avec le crédit du compte :

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

Le paiement prélève le crédit disponible jusqu’au montant dû et affiche status à SUCCEEDED. Un solde insuffisant laisse une partie due et le serveur attend le reste ; obtenez la facture et lisez amountDue, en centimes. Sans aucun crédit, l’appel répond 422 PAYMENT_FAILED.

providerType à STRIPE, avec l’ID d’une carte enregistrée dans methodId, débite cette carte. L’API ne liste les cartes enregistrées que dans les paramètres de l’organisation, qui nécessitent une session console ; une clé n’a donc aucun appel pour trouver cet ID. Sans methodId, STRIPE lance un paiement à confirmer dans un navigateur (Facturation).

Puis obtenez la commande environ toutes les 20 secondes jusqu’à ce que son article dans items affiche status à COMPLETED :

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

La commande elle-même affiche UNPAID jusqu’à l’exécution du provisionnement, puis COMPLETE. Le provisionedId de l’article est l’ID du nouveau serveur, le {serviceId} de tous les appels suivants. Un article à FAILED ne se rétablira pas seul : la commande affiche aussi FAILED et le support a besoin de son id pour la terminer.

Choisir un système d’exploitation

Listez les images compatibles avec le nouveau serveur :

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

Chaque image possède un id, un name, un slug comme ubuntu-24.04, une platform (LINUX ou WINDOWS), le defaultUser créé et les raidVariants pris en charge.

Déployer le système

Lancez le déploiement. image accepte l’id ou le slug de l’image ; sshKeyIds accepte les ID de Lister les clés SSH.

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

Un déploiement Linux nécessite un moyen de connexion : clé SSH, password ou votre propre cloudInit. Windows nécessite un password. username prend par défaut le defaultUser de l’image ; sous Linux, username et password s’appliquent avec les clés, et l’utilisateur nommé dispose de sudo sans mot de passe. raidVariant vaut NONE par défaut ; toute autre valeur doit figurer dans la liste de l’image.

La réponse est 201 avec l’opération en cours, de type DEPLOYMENT. Obtenez l’état du service pour la suivre :

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

operation contient le déploiement en cours avec progress et lastProgressMessage ; lastOperation.state vaut COMPLETED ou FAILED une fois terminé. Un déploiement ne démarre que si le state du service est ACTIVE ; si une autre opération s’exécute, l’API répond 409 avec OPERATION_IN_PROGRESS. Une fois COMPLETED, connectez-vous au primaryIpv4 renvoyé par Obtenir un service bare metal.