Présentation de l'API de SoftLayer

L'interface de programmation (API) de SoftLayer est l'interface de développement qui permet aux développeurs et aux administrateurs système d'interagir directement avec le système d'arrière-plan de SoftLayer. Les fonctionnalités exposées par notre API permettent aux utilisateurs de gérer et surveiller les serveurs à distance ainsi que d'extraire des informations des différents systèmes de SoftLayer, ce qui inclut par exemple la comptabilité, l'inventaire et les DNS. Notre API exploite un grand nombre des fonctions disponibles dans le portail client SoftLayer, ce qui signifie globalement que si une interaction est possible dans le portail client, cette interaction peut également être exécutée par notre API.

Qui doit utiliser l'API ?

L'API de SoftLayer (SLAPI) est à la disposition de tous les clients SoftLayer sans frais supplémentaires. Nous encourageons nos clients maîtrisant les bases de la programmation orientée objets à tirer pleinement parti des possibilités offertes par notre SLAPI. Les clients SoftLayer utilisent la SLAPI pour toutes sortes de tâches, mais la possibilité d'interagir programmatiquement avec toutes les composantes de l'environnement SoftLayer au sein de l'API amène la majorité de ces clients à exploiter la SLAPI pour l'automatisation des tâches.

Utilisation de l'API SoftLayer

Avant de commencer

La SLAPI permet aux utilisateurs d'interagir directement avec les objets qui exécutent le portail client. Avant tout développement avec la SLAPI, il y a hautement intérêt à comprendre les concepts de la programmation orientée vers les objets, ce qui inclut notamment les objets proprement dits, les propriétés, les méthodes et les héritages. Les méthodes de la SLAPI sont exécutées sur des objets de service au sein de nos systèmes d'arrière-plan, lesquels renvoient à la fois des objets de types de données propres à SoftLayer et des types de données standard tels que les entiers, les booléens et les chaînes.
La SLAPI est un système d'appel de procédure distante. Chaque appel implique l'envoi de données vers un point d'accès de l'API et la réception de données structurées en retour. Le format utilisé pour envoyer et recevoir des données avec la SLAPI va dépendre de l'implémentation que vous choisissez pour l'API. La SLAPI utilise actuellement les protocoles SOAP, XML-RPC ou REST pour la transmission des données. Avant de commencer à effectuer des appels API, vous aurez grand intérêt à comprendre comment utiliser ces protocoles dans votre langage de programmation ou votre langage de script. Vous pouvez utiliser l'une quelconque des implémentations dans votre application. Nous avons également prévu un certain nombre de clients API spécifiques au service ; disponibles dans plusieurs de nos langages pris en charge, ces clients sont accessibles sur notre profil github.

Création d'un utilisateur API

Chaque appel de la SLAPI est authentifié par un compte du portail client. Les comptes présents sur le portail client peuvent contenir plusieurs utilisateurs, mais nous recommandons fortement de créer un unique utilisateur du portail client pour l'exécution de tous les appels API. Que vous développiez une application ou que vous utilisiez une application API développée par d'autres, vous devez vous authentifier au sein de votre programme pour pouvoir accéder aux informations sur les différents aspects de votre compte et pour pouvoir interagir avec ces aspects. L'authentification vis-à-vis de la SLAPI nécessite votre nom d'utilisateur du portail client et votre clé API, ces éléments constituant un jeton d'authentification spécialement réservé aux appels de méthode API. Les droits utilisateur définis dans le portail client sont répercutés dans les appels API.

Choix entre réseau public et privé

Des serveurs de points d'accès SLAPI existent à la fois sur les réseaux public et privé. Vos applications basées API peuvent se connecter à partir de n'importe quel hôte sur l'Internet, mais le réseau privé de SoftLayer offre une couche supplémentaire de sécurité des données. De plus, SoftLayer met à disposition une multitude de points d'accès API de réseau privé, lesquels ne sont accessibles que si vous êtes connecté au réseau privé. Toutes les instances de serveur et de calcul associées à un compte SoftLayer ont une connexion directe au réseau privé et ces instances ne nécessitent pas d'authentification supplémentaire. Si vous voulez utiliser des points d'accès privés à partir d'un autre périphérique, une connexion VPN à notre réseau privé est nécessaire.

Concepts API de base

financiers

Un service est un point d'accès associé aux systèmes SoftLayer internes. Chaque service est une collection de méthodes ou d'actions pouvant être exécutées. Vous trouverez une liste complète des services SLAPI dans la section Référence de ce site.
Lorsque vous accédez à la section Services pour l'API désirée, vous voyez apparaître une liste de tous les services disponibles sur le côté gauche de l'écran. Chaque nom de service SoftLayer commence par "SoftLayer_" suivi d'un terme supplémentaire identifiant la fonction générale fournie par le service ; nous aurons ainsi les sous-ensembles "Hardware", "Account", "Billing", "Network", etc. Ce terme est lui-même suivi d'une autre terme qui définit la fonction spécifique du service au sein du sous-ensemble. Chaque service associé à l'API SoftLayer se voit attribuer un nom unique. Même si certains services tels que SoftLayer_Account ou SoftLayer_Account_Address peuvent partager un préfixe commun, leurs interactions ne sont pas nécessairement similaires et il n'y a pas d'héritage direct pour les services dont le nom inclut ce préfixe commun. Pour cette raison, chaque service doit être considéré de façon individuelle.
Pour visualiser les détails propres à un service donné, cliquez sur son nom. La page dédiée à chaque service affiche une liste des méthodes disponibles pour le service et bien souvent, cette page comporte également une brève présentation du service. Si chaque service offre un ensemble unique de méthodes, il se trouve qu'un grand nombre de services incluent la méthode getObject. Cette méthode permet d'extraire un objet de même type que le service appelé. Par exemple, si vous appelez la méthode getObject du service SoftLayer_Network_Subnet, vous obtenez un objet dont le type de données est SoftLayer_Network_Subnet.

Méthodes

Une méthode est une action spécifique que vous pouvez effectuer pour un service SLAPI donné. Chaque méthode renvoie un type de données scalaire ou structuré et peut nécessiter l'exécution de paramètres, de droits ou d'en-têtes spécifiques. Les paramètres des méthodes doivent être entrés via les techniques décrites dans la documentation propre à chaque langage ou point d'accès. Lorsque plusieurs paramètres sont nécessaires, vous devez les entrer dans l'ordre où ils apparaissent sur la page Méthode applicable, du haut vers le bas. La capture d'écran ci-dessous montre les paramètres nécessaires pour la méthode SoftLayer_Monitoring_Agent::getGraph. Quand vous exécuterez cette méthode, les paramètres devront donc se présenter dans l'ordre suivant : configurationValues, beginDate, endDate.
NOT FOUND: parameters.png
Une liste complète des paramètres, droits et en-têtes est disponible sur chaque page Méthode.

Types de données

Un type de données est une structure contenant une collection de valeurs scalaires et autres types de données. En plus des valeurs scalaires traditionnelles telles que chaîne, booléen ou entier, la SLAPI utilise des types de données complexes affectés de propriétés qui définissent les objets dirigés vers / renvoyés par les méthodes au sein de la SLAPI. Un certain nombre de propriétés locales, relationnelles et count sont potentiellement associées à chaque type de données.

Propriétés locales

Une propriété locale est un enfant direct d'un type de données. En règle générale, les propriétés locales sont renvoyées quand getObject() est appelé. Certaines propriétés locales, sinon toutes, sont nécessaires quand vous créez une instance du type de données lors d'un appel de createObject().

Propriétés relationnelles

Une propriété relationnelle est un enfant indirect d'un type de données. Les propriétés relationnelles sont définies dans d'autres types de données ou leurs propriétés. Par exemple, le type de données SoftLayer_Account a une propriété relationnelle au regard du matériel. Cette propriété est un tableau de types de données SoftLayer_Hardware. Quand elle est extraite avec un masque d'objet, la propriété relationnelle renvoie un tableau contenant un objet SoftLayer_Hardware pour chaque élément matériel présent sur le compte.

Propriétés count

Une propriété count est une propriété de "confort" permettant de déterminer le nombre total d'objets associés à une propriété donnée. Par exemple, nous pourrons extraire le nombre total de réseaux locaux virtuels associés à un serveur spécifique en utilisant un masque d'objet qui inclut Softlayer_Hardware_Server->networkVlanCount.

Concepts API avancés

En plus des actions types (création, lecture, mise à jour, suppression), la SLAPI permet aux développeurs de définir les modalités de retour des données suite à chaque appel, ceci au moyen d'en-têtes d'appel API spéciaux. Ces en-têtes offrent un niveau supplémentaire de contrôle sur la quantité de données renvoyée par l'API.

Limites de résultats

Une limite de résultats est une méthode d'appoint qui vous permet de définir une quantité d'objets à renvoyer ainsi qu'un décalage pour l'affichage de ces objets. Vous pouvez ainsi mettre en page de vastes ensembles de données.

Masques d'objet

Un masque d'objet permet d'une part d'indiquer quelles propriétés locales doivent être renvoyées par une méthode, et d'autre part d'extraire les informations présentes à la fois dans les propriétés relationnelles et dans les propriétés count. Une mappe, ou maskque, est créée pour définir les données spécifiques à inclure dans la valeur renvoyée. Par exemple, vous pouvez regrouper les ID pour chaque réseau privé virtuel sur un SoftLayer_Hardware_Server en spécifiant un masque d'objet pour networkVlans.id lors de l'appel de SoftLayer_Hardware_Server::getObject.

La maîtrise du SLAPI tient en partie à la capacité à naviguer entre différents masques d'objet pour obtenir les résultats escomptés. Le plus souvent, il y a plusieurs façons d'accéder à un point de données spécifique, et certaines peuvent être plus efficaces que d'autres.

Et maintenant ?

Maintenant que vous connaissez les bases, le moment est venu de commencer à coder. Reportez-vous à notre guide d'initiation pour voir comment créer un utilisateur API et procéder à votre premier appel. Par ailleurs, nous tenons à disposition un certain nombre de guides pour des langages spécifiques :

Autres liens utiles :