REST

SoftLayer met à disposition une API RESTful en plus des service API de style RPC. Vous utiliserez l'API REST dans les cas où votre langage de programmation ne prend peut-être pas bien en charge SOAP ou XML-RPC mais peut exécuter des opérations simples relevant du protocole HTTP et peut interpréter les données XML ou JSON.

URL REST

Les URL de l'API REST sont structurées de façon à pouvoir facilement traverser la hiérarchie des objets SoftLayer. Une demande REST de base s'organise comme suit :

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • Toutes les demandes REST, même sur réseau privé, doivent être transmises via HTTP SSL.
  • Utilisez votre nom d'utilisateur et votre clé API pour l'authentification HTTP de votre demande.
  • Le nom d'hôte de base / nom de dossier pour une demande REST est soit api.softlayer.com/rest/v3/, soit api.service.softlayer.com/rest/v3/. Vous utiliserez api.service.softlayer.com/rest/v3/ pour accéder à l'API REST sur le réseau privé de SoftLayer. La communication avec SoftLayer sera ainsi mieux sécurisée, sachant toutefois que le système qui effectue les appels API doit se trouver sur le réseau privé de SoftLayer (achat d'une licence auprès de SoftLayer ou connexion au réseau privé virtuel de SoftLayer).
  • Faites suivre l'URL de base du nom du service API que vous voulez appeler - exemples : "SoftLayer_Account" ou "SoftLayer_Hardware_Server".
  • Si votre demande API nécessite un paramètre d'initialisation, ajoutez à votre URL une barre oblique suivie de l'ID du paramètre.
  • L'API REST de SoftLayer peut renvoyer une sortie au format XML ou au format JSON. Ajoutez ".xml" ou ".json" à la fin de votre demande pour indiquer le format dans lequel vous souhaitez recevoir les données.

Une demande de ce type appelle la méthode getObject() du service API que vous sollicitez. SoftLayer_Account::getObject ne nécessite pas de paramètre d'initialisation et son URL REST se présente donc comme suit :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account.json

Toutefois, pour appeler la méthode getObject() pour un enregistrement SoftLayer_Hardware_Server spécifique, vous utiliserez l'URL suivante où "1234" représente l'ID du serveur auquel vous voulez accéder :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234.json

Pour appeler une méthode API autre que getObject(), placez le nom de la méthode à la suite de votre paramètre d'initialisation. Si le nom de votre méthode commence par "get", supprimez ces lettres et passez la première lettre du nom en majuscule. Vous pouvez également procéder ainsi pour accéder rapidement aux propriétés relationnelles d'un objet. Par exemple, la méthode getHardware() et la propriété relationnelle hardware du service API SoftLayer_Account pourront être atteintes à l'adresse suivante :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json

De la même façon, vous pouvez atteindre les composants réseau d'un serveur à l'URL suivante :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents.json

Pour une exploration aval de composants spécifiques d'un objet, chaînez une combinaison d'ID de paramètre d'initialisation et de propriétés relationnelles. Chaque ID ajouté explorera la propriété relationnelle spécifique. Par exemple, si vous voulez extraire le composant réseau du serveur 1234 dont l'ID est 5678, vous entrerez l'URL ci-après :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678.json

Et pour extraire la connexion montante de ce composant réseau :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678/uplinkNetworkComponents.json

Types de demande HTTP

DELETE

Une demande HTTP DELETE s'utilise en lieu et place de la méthode deleteObject() d'un service pour supprimer un objet. Par exemple, vous dirigerez une demande HTTP DELETE vers l'URL suivante pour supprimer l'enregistrement de domaine 1234 des serveurs DNS de SoftLayer :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

GET

Vous utiliserez les demandes HTTP GET pour les extractions d'objet et les appels de méthode simples. Par exemple, vous pourrez extraire l'ID d'enregistrement de domaine 1234 en dirigeant une demande HTTP GET vers l'URL suivante :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

POST

Une demande HTTP POST s'utilise en lieu et place des méthodes createObject() ou createObjects() d'un service pour créer un objet. Vous postez (POST) une structure JSON ou XML simple contenant un unique élément appelé "paramètre", lequel contient lui-même la structure élémentaire de votre objet ainsi que tout autre paramètre requis par la méthode createObject() de votre service API. Par exemple, vous dirigerez une demande HTTP POST avec les données indiquées vers l'URL ci-après pour créer un enregistrement de domaine dans les serveurs DNS de SoftLayer :

{
    "parameters" : [
        {
            "name" : "example.org",
            "resourceRecords" : [
                {
                    "type" : "a",
                    "host" : "@",
                    "data" : "127.0.0.1"
                }
            ]
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain.json

PUT

Une demande HTTP PUT s'utilise en lieu et place des méthodes editObject() ou editObjects() d'un service pour éditer un objet. Vous placez (PUT) une structure JSON ou XML simple contenant un unique élément appelé "paramètre", lequel contient lui-même la structure élémentaire de votre objet ainsi que tout autre paramètre requis par la méthode editObject() de votre service API. Par exemple, vous dirigerez une demande HTTP PUT avec les données indiquées vers l'URL ci-après pour éditer l'enregistrement de ressource de domaine 5678 dans les serveurs DNS de SoftLayer, la donnée étant modifiée en "10.0.0.1" :

{
    "parameters" : [
        {
            "data" : "10.0.0.1",
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234/ResourceRecords/5678.json

Transmission de paramètres de méthode

Les paramètres sont transmis dans notre API REST en ajoutant chacun de ces paramètres au chemin de l'URL.
Ils doivent être transmis dans le même ordre que celui de la liste dans la documentation associée à chaque méthode, du haut vers le bas.

Par exemple, SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber attend le paramètre userRecordId :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Monitoring_Agent/1234/setActiveAlarmSubscriber/5678.json

Certaines méthodes exigent un unique paramètre, à savoir un tableau tel que SoftLayer_Dns_Domain_ResourceRecord::createObjects :

 {
  "parameters":
    [
      [
        {"host":"hosta","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
        ,
        {"host":"hostb","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
      ]
    ]
}

Autres procédures pour définir le format des paramètres et des résultats

Parallèlement à l'ajout de ".json" ou ".xml" à votre URL REST, vous pouvez définir des formats pour les résultats de vos appels API en entrant un type MIME (application/json pour JSON et text/xml pour XML) dans les en-têtes HTTP Accept ou Content-Type de votre demande.

Utilisation de masques d'objet

Créez un masque d'objet dans l'URL de votre appel API en ajoutant une variable objectMask à votre chaîne de requête. Un masque d'objet est une liste de propriétés relationnelles séparées par des points-virgules, avec des propriétés relationnelles chaînées séparées par des points. Afin d'économiser de l'espace dans la chaîne de requête, les masques d'objet REST sont liés au type de données en fin d'URL plutôt qu'au service API sur lequel porte votre requête. Par ailleurs, les masques d'objet REST n'incluent pas de propriété mask.

L'URL ci-après crée un masque d'objet qui extrait les enregistrements de matériel d'un compte ainsi que les centres de données où se trouve ce matériel. À noter que le masque d'objet contient uniquement la propriété relationnelle que nous voulons extraire, laquelle est liée au matériel et non au compte.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter

L'URL qui suit extrait les enregistrements de matériel d'un compte, ainsi que les enregistrements de centre de données, de système d'exploitation et de composant réseau associés à ce matériel. Vous observez que ces éléments relationnels sont séparés par des points-virgules.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem;networkComponents

Cette autre URL extrait les enregistrements de matériel d'un compte, ainsi que les enregistrements de centre de données, de système d'exploitation, de mot de passe de système d'exploitation et de composant réseau associés à ce matériel. Les propriétés relationnelles chaînées sont séparées par des points.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem.passwords;networkComponents

L'API REST peut gérer les masques d'objet de façon légèrement différente par rapport aux API SOAP et XML-RPC de SoftLayer. Vous pouvez demander aux masques d'objet REST de filtrer les propriétés de type de données locales qui sont extraites de l'API SoftLayer. Si vous définissez une propriété locale dans votre masque, l'API SoftLayer traite ce masque comme un filtre et extrait uniquement les propriétés locales spécifiées dans le masque. Par exemple, l'URL suivante extrait uniquement l'ID et les propriétés de nom d'hôte dans les enregistrements de matériel d'un compte :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=hardware.id;hardware.hostname

Utilisation de limites de résultats

Pour limiter le nombre de résultats d'un appel API, vous devez ajouter une variable resultLimit à votre chaîne de requête. Vous définissez cette variable avec deux nombres séparés par une virgule et représentant :

  • le décalage à partir duquel doit s'afficher votre ensemble de résultats.
  • le nombre maximal de résultats pour votre appel.

L'URL ci-dessous extrait les deux premiers tickets ouverts sur un compte en appelant la méthode SoftLayer_Account::getOpenTickets :

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/OpenTickets.json?resultLimit=0,2

Traitement des erreurs

L'API REST de SoftLayer renvoie une sortie XML ou JSON avec un unique nœud d'erreur contenant tout message d'erreur consécutif à votre appel API. Par exemple, avec l'URL ci-après qui pointe vers un service inexistant :
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
vous allez voir apparaître le message d'erreur suivant :

>
   Service does not exist>
>

Et pour l'équivalent JSON :

https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.json

le message renvoyé sera libellé comme suit :

{
    "error": "Service does not exist"
}

Erreurs d'authentification

Si une combinaison nom d’utilisateur / clé API non valide est utilisée dans une demande d'URL REST, l'API REST de SoftLayer renvoie une erreur HTTP 401 Unauthorized.

Mises en garde

Spécification de types complexes

Comme pour XML-RPC, l'API REST ne peut pas déterminer les types complexes étendus dans certains paramètres. Pour cela, vous devez définir une propriété complexType dans votre ensemble de paramètres complexes en lui attribuant le type d'objet que vous transmettez à votre méthode.

Composants API référencés

financiers

Types de données

Méthodes