Prisma
Die Arbeit mit APIs ist großartig, aber manchmal muss man nicht mit der echten API arbeiten, um Entwicklungsarbeit zu leisten. Ein Werkzeug, das Sie in Ihren Entwicklungs-Workflow einbauen können, ist Prisma von Ampel. Prism ist ein Mock-Server, der unsere Live-APIs imitiert. Sie können ihn lokal ausführen, um Ihre API-Aufrufe während der Entwicklung zu testen, ohne dass Ihnen Nutzungskosten entstehen.
Prism versteht die OpenAPI specs, die wir für jede unserer APIs veröffentlichen, so dass Sie diesen Ansatz verwenden können, um mit jeder der Vonage APIs zu arbeiten.
Prisma installieren
Prism ist ein node.js-Tool, d. h. Sie müssen node.js lokal installiert haben. Vollständig Dokumentation und Installationsanweisungen sind verfügbar, aber die Schnellversion ist eine npm install Befehl:
npm install -g @stoplight/prism-cli
Überprüfen Sie, ob der Befehl installiert ist und funktioniert, indem Sie prism --version von einem Terminal aus.
Abrufen der OpenAPI-Spezifikation
Um die OpenAPI-Spezifikation für eine unserer APIs zu finden, navigieren Sie zu der entsprechenden API auf der Seite Homepage der Dokumentation. Wählen Sie die API-Referenz aus dem linken Menü aus und laden Sie über die Schaltfläche YAML-Download die API-Spezifikation herunter.
Sobald Sie die .yml Datei, die Sie wünschen, können Sie Prism starten.
Einen Mock-Server mit Prism starten
Starten Sie Prism im Terminal mit einem Befehl wie diesem:
prism mock [api-spec.yml]
Für Number Insights API zum Beispiel sehen mein Befehl und seine Ausgabe wie folgt aus:
$ 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
Die letzte Zeile der Ausgabe zeigt Ihnen, wo Prism ausgeführt wird; bei mir ist das lokal an Port 4010.
API-Anfragen an Prism stellen
Verwenden Sie die in der Startausgabe von Prism angezeigte URL als Basis-URL, um die Beispiel-API mit Ihrem bevorzugten HTTP-Client auszuprobieren. Im obigen Beispiel wurde die Number Insights API verwendet, sodass Sie eine Curl-Anfrage wie die folgende stellen können:
curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777"
Die Antwort von Prism enthält die gleichen Felder wie die Live-API und einige Beispielwerte, so dass sie beim Testen ein idealer Ersatz für die "echte" API ist.
Eine noch einfachere Möglichkeit, mit Prism zu arbeiten und API-Anfragen zu stellen, besteht darin, dieselbe OpenAPI-Spezifikation, die Sie Prism gegeben haben, in Postman zu importieren und die vorgefertigte Sammlung von Anfragen zu verwenden. Durch Ändern der {{baseUrl}} variabel, können Sie Postman und Prism schnell nutzen, um die Form jeder Vonage-API ohne Gebühren zu erkunden.
Verwendung von Prism mit Ihrer Applikation
Unsere SDKs bieten alle Unterstützung für das Ändern der Basis-URL, an die API-Anfragen gerichtet werden (ausführlich in der README jeder der Bibliotheken), damit Sie andere Endpunkte für Tests verwenden können.
Erweiterte Verwendung von Prism
Sobald Sie sich mit Prism vertraut gemacht haben, finden Sie hier einige Tipps, wie Sie Ihre Arbeit auf die nächste Stufe bringen können.
Anforderung einer spezifischen Antwort
Unsere APIs können in einigen Situationen Fehlerantworten zurückgeben, und es kann schwierig sein, diese Fehlersituationen auf der Live-Plattform nachzustellen. Die Verwendung von Prism bietet die Möglichkeit, Applikationen auf alle möglichen Antworten hin zu testen.
In einigen unserer API-Spezifikationen sind Fehlerantworten detailliert beschrieben, und Sie können den Namen der Antwort verwenden, um Prism zu bitten, sie zurückzugeben.
Bei der Verify-API finden Sie dies zum Beispiel in den Beispielantworten in der API-Spezifikation:
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
Standardmäßig gibt Prism die erste Antwort zurück. Das ist ein gutes Beispiel dafür, was die API normalerweise zurückgibt.
Es wäre jedoch nicht ideal, wenn Sie überprüfen könnten, ob Ihr Code einige dieser anderen möglichen Antworten verarbeitet. Hier kann Prism eine große Hilfe sein! Durch Anhängen einer __example Parameter zu Ihrer Anfrage hinzufügen, können Sie auswählen, welche der Beispiele Prism zurückgeben soll. Eine Curl-Anfrage an die Verify-API, die jedoch die "gedrosselte" Antwort zurückgeben soll, würde beispielsweise wie folgt aussehen:
curl "http://localhost:4010/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777&brand=Test&__example=throttled"
Wenn Sie Prism auf diese Weise verwenden, können Sie das Verhalten Ihrer Anwendung mit allen Antworten überprüfen, die die API zurückgeben kann.
Bessere JSON-Verarbeitung mit JQ
Wenn Sie mit JSON auf der Kommandozeile arbeiten, wie in den hier gezeigten curl-Beispielen, versuchen Sie das Tool jq um Ihre Arbeit mit JSON zu verbessern. Es ist ein großartiger Formatierer und kann bestimmte Felder aus der Antwort extrahieren oder die Daten auch auf andere Weise verarbeiten.
In seiner einfachsten Form können Sie es verwenden, um eine schönere Ausgabe des curl-Beispiels zu erhalten, das wir beim ersten Testen von Prism verwendet haben:
curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777" | jq "."