Hexatom - Documentation de l'API

Présentation de l'API

Cette API permet la gestion des différents services proposés par Hexatom. Cette API est toujours en cours de conception, de nouvelles fonctionnalités peuvent donc être ajoutées au fil du temps. Cette API vise à être rétrocompatible dans ses différentes mises à jour. En cas de changement majeur pouvant modifier la façon dont l'API fonctionne (breaking changes), une nouvelle version de l'API sera créé.

Cette API accepte et retourne ses résultats exclusivement en JSON.

À l'heure actuelle, l'accès à l'API n'est possible que sur autorisation préalable. N'hésitez pas à vous rapprocher de notre service client pour demander la création d'un token d'accès.

Authentification

L'accès à l'API se fait via l'utilisation d'un token unique. Chacune des requêtes est authentifiée grâce à ce token, envoyé via un header X-Auth-Token.

À l'heure actuelle, l'accès à l'API n'est possible que sur autorisation préalable. N'hésitez pas à vous rapprocher de notre service client pour demander la création d'un token d'accès.

curl -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' https://api.hexatom.fr/v1/user

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/user');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":{  
      "user_id":"123",
      "firstname":"Jean",
      "lastname":"Dupont",
      "companyname":"Ma Société",
      "email":"jean@dupont.fr"
   }
}

Codes d'erreur

error_code

invalid_token	Un token a bien été reçu par l'API, mais ce dernier est incorrect. Vérifiez que vous n'avez pas fait de faute de frappe.
no_token	Aucun token n'a été reçu par l'API. Vérifiez que vous l'envoyez bien un header `X-Auth-Token`

Endpoint

Cette API utilise un seul et unique endpoint pour la gestion de tous les services : https://api.hexatom.fr/{version}

À l'heure actuelle, la version de cette API est la v1. Le endpoint final est donc https://api.hexatom.fr/v1/

Attributs de réponse de l'API

status

Renvoie error en cas d'erreur de l'API, ou success dans le cas contraire
error_code optional

Retourne le code associé a l'erreur rencontrée. Ce paramètre n'est retourné que si le status est error. Voir gestion des erreurs pour les codes d'erreur globaux de l'API.
result

Retourne le contenu du résultat de la requête, sous forme d'un tableau

Gestion des erreurs

Chacune des requêtes adressées à l'API donne lieu à un retour (en format JSON) incluant la variable status. La valeur nominale de cette variable est success, ou bien error, lorsqu'une erreur a été rencontrée.

L'API utilise également des codes d'erreur HTTP afin de faciliter le traitement des éventuelles erreurs.

En cas d'erreur, une variable error_code est également renvoyée par l'API. Les différents codes d'erreurs globaux sont affichés ci-contre, et des codes d'erreurs supplémentaires sont décrits sur la documentation de chaque endpoint.

Exemple d'erreur

{  
   "status":"error",
   "error_code":"invalid_token"
}

Codes d'erreur globaux

error_code

invalid_token	Un token a bien été reçu par l'API, mais ce dernier est incorrect. Vérifiez que vous n'avez pas fait de faute de frappe.
no_token	Aucun token n'a été reçu par l'API. Vérifiez que vous l'envoyez bien un header `X-Auth-Token`
internal_api_error	L'API a rencontré une erreur interne, indépendante de votre dernière action.
permission_denied	Votre compte client ne dispose pas de l'autorisation pour accéder à cette fonctionnalité.
unknow_method	La méthode HTTP utilisée sur l'endpoint n'a pas été reconnue
no_json_input	L'API n'a pas reçu les données attendues en entrée au format JSON

Codes HTTP globaux

200 - OK	L'action s'est exécutée avec succès.
400 - Bad Request	Il y a une erreur au niveau des paramètres que vous avez envoyés à l'API.
401 - Unauthorized	L'authentification pour l'accès à l'API a échouée.
403 - Forbidden	L'accès à cette ressource n'est pas autorisé
404 - Not Found	La ressource demandée est introuvable.
409 - Conflict	Certains paramètres que vous avez envoyés entrent en conflit
500, 502, 503, 504 - Server Errors	Il y a eu une erreur interne de l'API. Ces erreurs sont indépendantes de vos actions.

API Index

Cet index liste la totalité des fonctionnalités disponibles sur l'API.

Certaines de ces fonctionnalités peuvent être soumises à autorisation préalable. Si votre compte n'est pas autorisé à utiliser une fonctionnalité, un code d'erreur permission_denied ainsi qu'un code HTTP 403 seront renvoyés (voir gestion des erreurs).

Pour plus d'informations concernant le fonctionnement de cette API, n'hésitez pas à consulter la partie authentification

USER : Get customer infos

GET https://api.hexatom.fr/v1/user

Retourne les informations générales concernant le compte client lié à la clef d'API utilisée.

Attributs de réponse

user_id

Identifiant unique du compte client connecté à l'API
firstname

Retourne le prénom lié au compte client
lastname

Retourne le nom lié au compte client
companyname

Retourne le nom de la société liée au compte client
email

Retourne l'adresse email liée au compte client

curl -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' https://api.hexatom.fr/v1/user

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/user');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":{  
      "user_id":"123",
      "firstname":"Jean",
      "lastname":"Dupont",
      "companyname":"Ma Société",
      "email":"jean@dupont.fr"
   }
}

Codes d'erreur

Il n'y a pas de code d'erreur spécifique à ce endpoint. Voir gestion des erreurs pour les codes d'erreur globaux de l'API.

HPC : Get server infos

GET https://api.hexatom.fr/v1/hpc/{server_id}

Retourne les informations liées au serveur HPC passé en paramètre

Paramètres d'entrée

server_id (GET)

Identifiant unique du serveur dont vous souhaitez obtenir les informations (voir HPC : List all servers)

Attributs de réponse

server_id

Identifiant unique du serveur
offer_name

Nom commercial de l'offre correspondant à ce serveur
status

Retourne le statut de ce serveur.
Active correspond à un serveur livré et fonctionnel
Building correspond à un serveur en cours de livraison
Cancelled correspond à un serveur qui a été résilié
template

Retourne l'identifiant unique de la template utilisée pour provisionner ce serveur.
mac optional

Retourne l'adresse MAC du serveur (uniquement si le serveur est en statut Active)
ip optional

Retourne l'IP du serveur (uniquement si le serveur est en statut Active). Ce champ retourne "N/A" si la gestion IP est géré par le DHCP du client.
hostname optional

Retourne l'hostname du serveur (uniquement si le serveur est en statut Active ou Cancelled).
activation_date optional

Retourne la date de livraison de ce serveur, au format timestamp UNIX (uniquement si le serveur est en statut Active ou Cancelled).
cancellation_date optional

Retourne la date de résiliation de ce serveur, au format timestamp UNIX (uniquement si le serveur est en statut Cancelled).
monthly_usage_euros optional

Retourne le coût d'utilisation de ce serveur en euros. Ce compteur est remis à zéro en début de mois (uniquement si le serveur est en statut Active).
monthly_usage_hours optional

Retourne le nombre d'heure d'utilisation de ce serveur. Ce compteur est remis à zéro en début de mois (uniquement si le serveur est en statut Active).

curl -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx' https://api.hexatom.fr/v1/hpc/1234

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/hpc/1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');


$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":{  
      "server_id":1234,
      "offer_name":"RENDER-40T-120G",
      "status":"Active",
      "mac":"B2:9F:8A:16:CC:37",
      "ip":"10.0.0.1",
      "hostname":"CUSTHPC1234",
      "activation_date":"1568635776",
      "template":123,
      "monthly_usage_euros":"12.34",
      "monthly_usage_hours":123
   }
}

Codes d'erreur

error_code

nonexistent_server	Aucun serveur avec l'identifiant `{server_id}` n'a été trouvé (ou bien ce dernier n'est pas rattaché à ce compte client)

HPC : List all servers

GET https://api.hexatom.fr/v1/hpc/list

Retourne la liste de tous les serveurs HPC en cours de location (statut Active ou Building), ainsi que les informations de base concernant ces serveurs.

Attributs de réponse

server_id

Identifiant unique du serveur
status

Retourne le statut de ce serveur.
Active correspond à un serveur livré et fonctionnel
Building correspond à un serveur en cours de livraison
template

Retourne l'identifiant unique de la template utilisée pour provisionner ce serveur.
mac optional

Retourne l'adresse MAC du serveur (uniquement si le serveur est en statut Active)
ip optional

Retourne l'IP du serveur (uniquement si le serveur est en statut Active). Ce champ retourne "N/A" si la gestion IP est géré par le DHCP du client.
hostname optional

Retourne l'hostname du serveur (uniquement si le serveur est en statut Active ou Cancelled).

curl -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx' https://api.hexatom.fr/v1/hpc/list

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/hpc/list');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');


$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":[  
      {  
         "server_id":1234,
         "hostname":"CUSTHPC1234",
         "status":"Active",
         "template":123,
         "ipaddress":"N\/A",
         "mac":"B2:9F:8A:16:CC:37"
      },
      {  
         "server_id":1235,
         "status":"Building",
         "template":123,
      }
   ]
}

Codes d'erreur

Il n'y a pas de code d'erreur spécifique à ce endpoint. Voir gestion des erreurs pour les codes d'erreur globaux de l'API.

HPC : List offers & stocks

GET https://api.hexatom.fr/v1/hpc/offers

Retourne la liste des offres HPC disponibles, ainsi que les stocks disponibles immédiatement pour ces offres.

Attributs de réponse

offer_id

Retourne l'identifiant unique de l'offre
offer_name

Retourne le nom commercial de l'offre
memory

Retourne la quantité de RAM allouée aux serveurs de cette offre
storage

Retourne la quantité et le type de stockage alloué aux serveurs de cette offre
stock

Retourne la quantité de serveurs qui sont disponible immédiatement pour une nouvelle commande

curl -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx' https://api.hexatom.fr/v1/hpc/offers

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/hpc/offers');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');


$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":[  
      {  
         "offer_id":"123",
         "offer_name":"RENDER-40T-60G",
         "memory":"60 Go",
         "storage":"SSD 400Go",
         "stock":123
      },
      {  
         "offer_id":"124",
         "offer_name":"RENDER-40T-120G",
         "memory":"120 Go",
         "storage":"SSD 400Go",
         "stock":1123
      }
   ]
}

Codes d'erreur

Il n'y a pas de code d'erreur spécifique à ce endpoint. Voir gestion des erreurs pour les codes d'erreur globaux de l'API.

HPC : List templates

GET https://api.hexatom.fr/v1/hpc/templates

Retourne la liste des templates HPC attribuées au compte client. Ces templates peuvent être utilisées pour générer une nouvelle commande, en utilisant HPC : Order servers

Attributs de réponse

template_id

Retourne l'identifiant unique de la template
name

Retourne le nom de la template
description

Retourne une courte description de la template
create_date

Retourne la date de création de la template

curl -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx' https://api.hexatom.fr/v1/hpc/templates

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/hpc/templates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');


$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":[  
      {  
         "template_id":"123",
         "name":"TEMPLATE-001",
         "description":"Template de test numéro 1",
         "create_date":"1558561264"
      },
      {  
         "template_id":"124",
         "name":"TEMPLATE-002",
         "description":"Template de test numéro 2",
         "create_date":"1558561265"
      }
   ]
}

Codes d'erreur

Il n'y a pas de code d'erreur spécifique à ce endpoint. Voir gestion des erreurs pour les codes d'erreur globaux de l'API.

HPC : Cancel server

DELETE https://api.hexatom.fr/v1/hpc/{server_id}

Lance la résiliation immédiate du serveur {server_id}. Attention, ce endpoint détruit immédiatement les données du serveur concerné.

Paramètres d'entrée

server_id (GET)

Identifiant unique du serveur dont vous souhaitez la résiliation immédiate (voir HPC : List all servers)

curl -x DELETE -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx' https://api.hexatom.fr/v1/hpc/1234

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/hpc/1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');


$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":"This server has been cancelled"
}

Codes d'erreur

error_code

non_active	Ce serveur n'est pas en status `Active`. Les serveurs en status `Cancelled` ou `Building` ne peuvent pas être résiliés.
nonexistent_server	Aucun serveur avec l'identifiant `{server_id}` n'a été trouvé (ou bien ce dernier n'est pas rattaché à ce compte client)

HPC : Order servers

POST https://api.hexatom.fr/v1/hpc/order

Lance la création d'une commande pour un provisioning immédiat.

Paramètres d'entrée

offer_id (POST)

Identifiant unique de l'offre dont vous souhaitez passer commande (voir HPC : List offers & stocks)
template_id (POST)

Identifiant unique de la template à utiliser pour l'installation des serveurs (voir HPC : List templates)
quantity (POST)

Nombre de serveur dont vous souhaitez passer commande (voir HPC : List offers & stocks)

curl -x POST -d '{"offer_id":25, "template_id":5, "quantity":1}' -H 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx' https://api.hexatom.fr/v1/hpc/order

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.hexatom.fr/v1/hpc/order');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"offer_id\":123, \"template_id\":123, \"quantity\":123}");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');


$headers = array();
$headers[] = 'X-Auth-Token: xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxxxxx';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

Réponse

{  
   "status":"success",
   "result":"An order has been placed"
}

Codes d'erreur

error_code

nonexistent_template	La template demandée n'existe pas, ou n'est pas lié à ce compte client. Voir HPC : List templates
nonexistent_offer	L'offre demandée n'existe pas. Voir HPC : List offers & stocks
exceeded_stock	Votre commande dépasse le nombre de serveurs en stock pour cette offre. Voir HPC : List offers & stocks
quantity_is_null	Vous avez essayé de placer une commande avec une quantité égale à zéro (ou bien vous n'avez pas indiqué la quantité)

Présentation de l'API

Authentification

Réponse

Codes d'erreur

Endpoint

Attributs de réponse de l'API

status

error_code optional

result

Gestion des erreurs

Exemple d'erreur

Codes d'erreur globaux

Codes HTTP globaux

API Index

USER : Get customer infos

Attributs de réponse

user_id

firstname

lastname

companyname

email

Réponse

Codes d'erreur

HPC : Get server infos

Paramètres d'entrée

server_id (GET)

Attributs de réponse

server_id

offer_name

status

template

mac optional

ip optional

hostname optional

activation_date optional

cancellation_date optional

monthly_usage_euros optional

monthly_usage_hours optional

Réponse

Codes d'erreur

HPC : List all servers

Attributs de réponse

server_id

status

template

mac optional

ip optional

hostname optional

Réponse

Codes d'erreur

HPC : List offers & stocks

Attributs de réponse

offer_id

offer_name

memory

storage

stock

Réponse

Codes d'erreur

HPC : List templates

Attributs de réponse

template_id

name

description

create_date

Réponse

Codes d'erreur

HPC : Cancel server

Paramètres d'entrée

server_id (GET)

Réponse

Codes d'erreur

HPC : Order servers

Paramètres d'entrée

offer_id (POST)

template_id (POST)

quantity (POST)

Réponse

Codes d'erreur