Évaluer les API rapidement et facilement avec OpenAPI

Chez Nexmo, nous publions les spécifications OpenAPI pour toutes nos API. Cela permet aux développeurs d'explorer, d'évaluer et d'intégrer plus facilement nos API dans leurs propres Applications. Lisez la suite pour en savoir plus sur OpenAPI et sur la raison pour laquelle nous partageons ces spécifications d'API avec les développeurs.

Qu'est-ce que l'OpenAPI ?

OpenAPI est un moyen lisible par la machine de décrire une API. Elle est écrite en YAML ou en JSON et décrit l'objectif général, le mécanisme d'authentification et d'autres détails de l'API (si vous avez entendu parler de Swagger, OpenAPI en est le successeur). Il décrit également en détail chacun des points de terminaison de l'API. Par exemple, voici un extrait de notre API Account, qui montre comment vous pouvez vérifier le solde de votre compte Nexmo :

/account/get-balance:
    servers:
      - url: "https://rest.nexmo.com"
    get:
      operationId: getAccountBalance
      summary: Get Account Balance
      description: Retrieve the current balance of your Nexmo account
      parameters:
        name: api_key
        description: Your Nexmo API key. You can find this in the [dashboard](${CUSTOMER_DASHBOARD_URL})
        in: query
        required: true
        schema:
          type: string
          example: abcd1234
        name: api_secret
        description: Your Nexmo API secret. You can find this in the [dashboard](${CUSTOMER_DASHBOARD_URL})
        in: query
        required: true
        schema:
          type: string
          example: ABCDEFGH01234abc

Comme vous pouvez le constater, le format de description de l'API est très verbeux. C'est parce qu'il doit décrire une API si bien que même les machines peuvent la comprendre. L'exemple présenté ici contient l'URL, le verbe et les paramètres nécessaires pour obtenir des informations sur le solde du compte. La spécification fournit également un moyen de décrire les statuts des réponses et les données utiles qui peuvent être renvoyées, à la fois les réponses positives et les autres !

Télécharger une spécification OpenAPI

Les spécifications OpenAPI sont largement utilisées par les fournisseurs d'API. La spécification lisible par une machine peut être très utile dans le cycle de développement, en permettant la génération automatisée de code, les tests et les SDK de bibliothèque.

Cependant, la spécification OpenAPI devient encore plus utile lorsqu'elle est largement partagée en dehors de l'organisation du fournisseur d'API. C'est un bon indicateur des pratiques modernes en matière d'API, et il est beaucoup plus rapide d'obtenir un fichier au format standard à utiliser dans vos propres outils que de parcourir une documentation peu familière à la recherche d'informations. De nombreux fournisseurs d'API proposent des spécifications OpenAPI pour leurs API et nous en sommes ravis :)

Si vous consultez une page de référence de l'API Nexmo, vous verrez un bouton comme celui-ci :

A big blue Download OpenAPI 3 Description button

La documentation de référence de l'API est générée à partir de la spécification OpenAPI elle-même, et en cliquant sur le bouton de téléchargement, vous obtiendrez le fichier YAML source. Vous pouvez également trouver toutes nos spécifications sur GitHub.

Explorer l'API dans Postman

Ce que nous préférons faire avec un fichier OpenAPI que nous n'avons pas vu auparavant est de l'importer dans Postman. Si vous n'êtes pas encore familier avec cet excellent outil, il s'agit d'un client HTTP très agréable qui s'avère très utile lorsque l'on travaille avec des API (c'est en fait bien plus que cela, vérifiez-le par vous-même).

Postman prend désormais en charge les fichiers OpenAPI v3. Vous pouvez importer un fichier lors de la création d'une collection :

Shows the import dialog when creating a collection

L'importation d'une spécification OpenAPI produit une "collection" de demandes d'API prête à l'emploi, et une demande est déjà créée pour chaque point d'extrémité individuel. Vous pouvez rapidement ajouter votre clé API, votre secret et tout autre paramètre nécessaire à cette requête et l'exécuter.

check balance postman

Je trouve que c'est un moyen tellement rapide d'explorer une API que je ne connais pas. Plutôt que d'avoir à lire la documentation et à reconstituer des exemples d'appels d'API pour essayer de déterminer si cette API particulière répondra à mes besoins, tout est sous mes yeux.

Conseil de pro : n'hésitez pas à essayer maintenant avec l'API Nexmo. Vous devez créer un Account mais ne vous inquiétez pas, il y a un petit crédit gratuit pour vous permettre de jouer.

Générez votre propre SDK

Chez Nexmo, nous publions des SDK de serveur dans six piles technologiques et demie différentes - mais tous les fournisseurs d'API ne le font pas, ou n'offrent pas le langage de programmation que vous recherchez. À mi-chemin entre un SDK décent et rien du tout, vous pouvez utiliser un générateur de code pour créer une enveloppe de base pour l'API. Consultez la section "Générateurs de SDK" sur le site https://openapi.tools/#sdk pour des exemples.

Le fait de disposer du "vrai" SDK ou d'un SDK généré peut accélérer considérablement les intégrations d'API ; les fonctions d'autocomplétion dans votre IDE sont beaucoup plus rapides que la recherche d'informations dans la documentation à chaque étape. La génération d'un SDK pour une seule partie de l'API peut également entraîner une réduction des dépendances ou de la base de code, ce qui, dans certaines situations, est vraiment important. Le choix d'un fournisseur d'API qui vous fournira la spécification OpenAPI est très utile dans ces scénarios.

Note de l'éditeur : En savoir plus sur OpenAPI

Si vous souhaitez en savoir plus sur OpenAPI, pourquoi ne pas venir à notre Vonage Campus à San Francisco ? Lorna (l'auteur de ce billet) sera présente pour donner une conférence sur OpenAPI - et elle adore discuter d'OpenAPI en général. C'est donc une excellente occasion de passer du temps avec les gens de Nexmo et de parler d'API.