Schnelle und einfache Bewertung von APIs mit OpenAPI

Bei Nexmo veröffentlichen wir OpenAPI-Spezifikationen für alle unsere APIs. Das macht es für Entwickler einfacher, unsere APIs zu erkunden, zu bewerten und in ihre eigenen Anwendungen zu integrieren. Lesen Sie weiter, um mehr über OpenAPI zu erfahren und warum wir diese API-Spezifikationen mit Entwicklern teilen.

Was ist OpenAPI?

OpenAPI ist eine maschinenlesbare Methode zur Beschreibung einer API. Sie wird entweder in YAML oder JSON geschrieben und beschreibt den Gesamtzweck, den Authentifizierungsmechanismus und andere Details der API (falls Sie schon von Swagger gehört haben, ist OpenAPI der Nachfolger davon). Außerdem werden die einzelnen Endpunkte der API im Detail beschrieben. Hier ist zum Beispiel ein Auszug aus unserer Account API, der zeigt, wie Sie den Kontostand Ihres Nexmo-Kontos überprüfen können:

/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

Wie Sie sehen können, ist das API-Beschreibungsformat sehr ausführlich. Das liegt daran, dass eine API so gut beschrieben werden muss, dass sogar die Maschinen sie verstehen können. Das hier gezeigte Beispiel enthält die URL, das Verb und die Parameter, die erforderlich sind, um Informationen über den Kontostand zu erhalten. Die Spezifikation bietet auch eine Möglichkeit, den Status der Antworten und die Nutzdaten zu beschreiben, die zurückgegeben werden können, sowohl die erfolgreichen als auch die anderen!

Download einer OpenAPI-Spezifikation

OpenAPI-Spezifikationen sind in den Unternehmen der API-Anbieter weit verbreitet. Die maschinenlesbare Spezifikation kann im Entwicklungszyklus sehr leistungsfähig sein, da sie eine automatisierte Codegenerierung, Tests und Bibliotheks-SDKs ermöglicht.

Die OpenAPI-Spezifikation wird jedoch noch nützlicher, wenn sie auch außerhalb der eigenen Organisation des API-Anbieters verbreitet wird. Sie ist ein guter Indikator für moderne API-Praktiken, und es ist viel schneller, sich eine Datei im Standardformat zu besorgen, um sie in den eigenen Tools zu verwenden, als sich auf der Suche nach Informationen durch eine unbekannte Dokumentation zu wühlen. Wir sehen viele API-Anbieter, die OpenAPI-Spezifikationen für ihre APIs anbieten, und wir finden das gut :)

Wenn Sie sich eine Nexmo-API-Referenzseite ansehen, werden Sie eine Schaltfläche wie diese sehen:

A big blue Download OpenAPI 3 Description button

Die API-Referenzdokumentation wird aus der OpenAPI-Spezifikation selbst generiert. Wenn Sie auf die Schaltfläche "Download" klicken, erhalten Sie die YAML-Quelldatei. Sie können auch alle unsere Spezifikationen finden auf GitHub.

Erkunden Sie die API in Postman

Unsere Lieblingsbeschäftigung mit einer OpenAPI-Datei, die wir noch nicht gesehen haben, ist der Import in Postman. Falls Sie dieses hervorragende Tool noch nicht kennen, es ist ein wirklich netter HTTP-Client, der bei der Arbeit mit APIs sehr nützlich ist (eigentlich ist es viel mehr als das, probieren Sie es selbst aus).

Postman unterstützt jetzt auch OpenAPI v3-Dateien. Sie können eine Datei importieren, wenn Sie eine Sammlung erstellen:

Shows the import dialog when creating a collection

Beim Importieren einer OpenAPI-Spezifikation wird eine fertige "Sammlung" von API-Anfragen erstellt, und für jeden einzelnen Endpunkt wurde bereits eine Anfrage für Sie erstellt. Sie können schnell Ihren API-Schlüssel, Ihr Geheimnis und alle anderen für diese Anfrage benötigten Parameter hinzufügen und die Anfrage ausführen.

check balance postman

Ich finde, dass dies ein schneller Weg ist, eine API zu erkunden, mit der ich nicht vertraut bin. Anstatt die Dokumentation zu lesen und einige API-Beispielaufrufe zusammenzustellen, um herauszufinden, ob diese bestimmte API meinen Anforderungen entspricht, habe ich alles direkt vor Augen.

Profi-Tipp: Sie können dies jetzt mit der Nexmo API ausprobieren. Sie müssen sich einen Account einrichten anmelden, aber keine Sorge, Sie erhalten ein kleines kostenloses Guthaben, mit dem Sie spielen können.

Erzeugen Sie Ihr eigenes SDK

Bei Nexmo veröffentlichen wir Server-SDKs in sechseinhalb verschiedenen Tech-Stacks - aber nicht jeder API-Anbieter bietet die Programmiersprache an, nach der Sie gesucht haben, oder vielleicht auch nicht. Als Mittelweg zwischen einem anständigen SDK und gar nichts, können Sie einen Code-Generator verwenden, um einen einfachen Wrapper für die API zu erstellen. Sehen Sie sich den Abschnitt "SDK-Generatoren" auf https://openapi.tools/#sdk für einige Beispiele.

Wenn Sie entweder das "echte" SDK oder ein generiertes SDK haben, können Sie die API-Integration erheblich beschleunigen; automatische Vervollständigungsfunktionen in Ihrer IDE sind viel schneller, als wenn Sie bei jedem Schritt in der Dokumentation nachschlagen. Die Generierung eines SDKs für nur einen Teil der API kann auch zu weniger Abhängigkeiten oder einer kleineren Codebasis führen, was in manchen Situationen sehr wichtig ist. Die Wahl eines API-Anbieters, der Ihnen die OpenAPI-Spezifikation zur Verfügung stellt, ist in diesen Szenarien sehr hilfreich.

Anmerkung der Redaktion: Erfahren Sie mehr über OpenAPI

Wenn Sie mehr über OpenAPI erfahren möchten, kommen Sie doch zu unserer Vonage Campus-Veranstaltung in San Francisco? Lorna (die Autorin dieses Beitrags) wird dort einen Vortrag über OpenAPI halten - und sie liebt es, über OpenAPI im Allgemeinen zu plaudern, so dass es eine gute Gelegenheit ist, mit den Nexmo-Leuten abzuhängen und über APIs zu sprechen.