Faisons un petit break avec REST

Dans notre dernier article, vous avez pu lire que notre API se prêtait désormais à une interface REST. Et vous avez bien lu, cette interface est réellement prise en charge ! Petit extrait de notre nouvelle page du manuel :

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

https://:@api.[service.]softlayer.com/rest/v3/
[/initializationParameter].

  • 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.

 

Maintenant que la purge est passée, voici quelques exemples d'appel :

L'appel le plus basique dans l'API SoftLayer est la méthode getObject() du service API SoftLayer_Account. Cet appel a aussi l'URL la plus simple dans notre API REST :

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

 

Si vous avez besoin d'extraire un objet particulier, vous ajoutez son numéro d'identification à la fin de l'URL. Ainsi, l'URL ci-après va extraire des informations sur l'enregistrement 1234 de SoftLayer_Hardware_Server :

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

 

L'une des choses les plus "cool" dans notre API, c'est la façon dont nos objets sont en relation les uns avec les autres. Pour extraire les objets liés à un objet donné, vous ajoutez une propriété relationnelle à la fin de votre URL. Ainsi, l'URL ci-après va extraire les enregistrements composant réseau du serveur 1234 :

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

 

Vous pouvez chaîner ces propriétés relationnelles autant que nécessaire. Vous pouvez également spécifier une unique propriété relationnelle en ajoutant son ID à la fin de l'URL. L'URL suivante, par exemple, va extraire l'enregistrement de composant réseau 5678 de l'enregistrement de serveur 1234 :

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

 

Puisque les enregistrements de matériel renvoient au service SoftLayer_Account, votre URL peut tout aussi bien renvoyer à ce service. Votre enregistrement SoftLayer_Account a des propriétés pour la quasi totalité des services proposés, et c'est un moyen pratique pour disposer d'une interface réellement RESTful.

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

 

Je suis absolument épaté de voir à quel point ça fonctionne bien. Avec la possibilité de tester les fonctionnalités de l'API directement dans mon navigateur Web, le traitement des incidents est devenu beaucoup plus facile pour moi. Notre interface REST prend également en charge la création, l'édition et la suppression d'objets, ainsi que des options spécifiques à l'API SoftLayer comme par exemple les masques d'objet et les limites de résultats. Reportez-vous à notre page du manuel pour le scoop. Nous vous invitons à faire un essai et à nous dire ce que vous en pensez. Et bientôt, encore quelques bonnes surprises pour vous !