Prisme

Travailler avec des API est une excellente chose, mais il arrive que vous n'ayez pas besoin de travailler avec l'API réelle pour effectuer votre travail de développement. Un outil que vous pouvez trouver utile d'inclure dans votre flux de travail de développement est Prisme de Feu rouge. Prism est un serveur fictif qui imite nos API actives. Vous pouvez l'exécuter localement pour tester vos appels d'API pendant le développement, sans encourir de frais d'utilisation.

Prism comprend la OpenAPI que nous publions pour chacune de nos API, de sorte que vous pouvez utiliser cette approche pour travailler avec n'importe quelle API de Vonage.

Installer Prism

Prism est un outil node.js, vous devez donc avoir node.js installé localement. Complet documentation et instructions d'installation sont disponibles, mais la version rapide est un npm install commande :

npm install -g @stoplight/prism-cli

Vérifiez que la commande est installée et fonctionne en exécutant prism --version à partir d'un terminal.

Obtenir la spécification OpenAPI

Pour trouver la spécification OpenAPI de l'une de nos API, naviguez jusqu'à l'API en question à partir de la page Page d'accueil de la documentation. Sélectionnez la référence de l'API dans le menu de gauche et utilisez le bouton de téléchargement YAML pour télécharger la spécification de l'API.

An example of the Download OpenAPI Specification section

Une fois que vous avez le .yml vous voulez, vous êtes prêt à démarrer Prism.

Démarrer un serveur fictif avec Prism

Depuis le terminal, démarrez prism avec une commande comme celle-ci :

prism mock [api-spec.yml]

Par exemple, pour Number Insight API, ma commande et son résultat ressemblent à ceci :

$ prism mock number-insight.yml
[12:13:06] › [CLI] …  awaiting  Starting Prism…
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/basic/json?number=1%295-2%209%2B2&country=UV
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/standard/xml?number=67-64%298427&country=OU&cnam=false
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/advanced/async/json?callback=sunt%20deserunt%20dolore%20id&number=%2B1208&country=CM&cnam=false&ip=accusamus
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/advanced/xml?number=-47&country=MU&cnam=false&ip=non
[12:13:06] › [CLI] ▶  start     Prism is listening on http://127.0.0.1:4010

La dernière ligne de la sortie vous indique où Prism s'exécute ; pour moi, c'est localement sur le port 4010.

Faire des demandes d'API à Prism

Avec l'URL indiquée dans la sortie de démarrage de Prism comme URL de base, utilisez votre client HTTP préféré pour essayer l'API de l'exemple. L'exemple ci-dessus utilisait l'API Number Insight, vous pouvez donc effectuer une requête curl comme celle-ci :

curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777"

La réponse de Prism contient les mêmes champs que l'API réelle et quelques valeurs d'exemple, ce qui en fait un substitut idéal à la "réalité" lors des tests.

Pour travailler encore plus facilement avec Prism et faire des demandes d'API, essayez d'importer dans Postman la même spécification OpenAPI que vous avez donnée à Prism et utilisez la collection de demandes déjà prête. En changeant l'élément {{baseUrl}} variable, vous pouvez rapidement utiliser Postman et Prism pour explorer la forme de n'importe quelle API de Vonage sans frais.

Utilisez Prism avec votre application

Nos SDK permettent tous de modifier l'URL de base vers laquelle les demandes d'API sont dirigées (voir les détails dans la section README de chacune des bibliothèques) pour vous permettre d'utiliser d'autres points d'extrémité pour les tests.

Utilisation avancée de Prism

Une fois que vous avez pris vos marques avec Prism, voici quelques conseils pour passer à l'étape suivante.

Demander une réponse spécifique

Nos API peuvent renvoyer des réponses d'erreur dans certaines situations, et il peut être difficile de recréer ces situations d'erreur sur la plateforme live. L'utilisation de Prism permet de tester les applications en fonction de toutes les réponses possibles.

Certaines de nos spécifications d'API ont des réponses d'erreur décrites en détail, et vous pouvez utiliser le nom de la réponse pour demander à Prism de la renvoyer.

Par exemple, dans l'API Verify, vous trouverez ceci dans les exemples de réponses dans la spécification de l'API :

              examples:
                success:
                  summary: Request was started
                  value:
                    request_id: abcdef0123456789abcdef0123456789
                    status: "0"

                throttled:
                  summary: Request limit exceeded
                  value:
                    status: "1"
                    error_text: Throttled

                account-disabled:
                  summary: Account is barred
                  value:
                    status: "8"
                    error_text: The api_key you supplied is for an account that has been barred from submitting messages.

                rejected:
                  summary: Rejected
                  value:
                    status: "15"
                    error_text: The destination number is not in a supported network

Par défaut, Prism renvoie la première réponse, ce qui est très bien, car c'est un bon exemple de ce que l'API renvoie habituellement.

Cependant, il ne serait pas idéal de vérifier que votre code gère certaines de ces autres réponses possibles. C'est là que Prism peut être d'une grande aide ! En ajoutant un __example à votre requête, vous pouvez sélectionner l'exemple que Prism doit renvoyer. Par exemple, pour envoyer une requête curl à l'API Verify, mais pour qu'elle renvoie la réponse "throttled", cela ressemblerait à ceci :

curl "http://localhost:4010/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777&brand=Test&__example=throttled"

En utilisant Prism de cette manière, vous pouvez vérifier le comportement de votre application avec toutes les réponses que l'API peut renvoyer.

Meilleure gestion de JSON avec JQ

Si vous travaillez avec JSON en ligne de commande, comme dans les exemples curl présentés ici, essayez l'outil jq pour améliorer votre façon de travailler avec JSON. C'est un excellent formateur, qui peut extraire des champs particuliers de la réponse ou traiter les données d'autres manières.

Dans sa forme la plus simple, vous pouvez l'utiliser pour obtenir une meilleure sortie de l'exemple curl que nous avons utilisé lorsque nous avons testé Prism pour la première fois :

curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777" | jq "."