Onboarding von Entwicklern mit API-Sammlungen

Einführung

In diesem Beitrag erörtern wir, wie ein produktbezogener Ansatz für die Gestaltung von APIs mit API-Sammlungen, die mit Tools wie Postman, Bruno oder Insomnia erstellt wurden, als Onboarding-Artefakte sehr effektiv sein können.

Bei diesen Sammlungen handelt es sich um interaktive Leitfäden, die Entwicklern dabei helfen, mit Arbeitsabläufen anhand realer Daten zu experimentieren, Reibungsverluste zu verringern und schneller produktiv zu werden. Sie sind mehr als nur Anforderungsersteller.

Wir werden den Grund untersuchen, warum OpenAPI-Spezifikationen zwar wertvoll sind, aber bei der Förderung der tatsächlichen Akzeptanz scheitern. Wir werden auch erörtern, wie Sammlungen die Geschichte Ihrer API vermitteln, mit versionierten Codebases konsistent bleiben und eine Kultur der Benutzerfreundlichkeit und Iteration ermöglichen können.

Voraussetzungen

Um mitzumachen, brauchen Sie:

• Ein Tool wie Postman, Bruno oder Insomnia (Beispiele verwenden Postman)

• Zugang zu Vonage API-Schlüsseln oder einer Testumgebung

• Vertrautheit mit grundlegenden API-Konzepten

Was ist eine API-Sammlung?

Eine API-Sammlung ist ein vordefinierter Satz von Anfragen, die zeigen, wie man mit einer API in einer organisierten, beispielhaften Weise arbeitet. Sie werden typischerweise in Tools wie Postman, Bruno oder Insomnia verwendet, aber Sie können sie auch mit strukturierten cURL-Skripten erstellen.

Was Sammlungen besonders leistungsfähig macht, ist ihre Interaktivität. Anstatt über einen Endpunkt zu lesen, können Entwickler ihn ausführen, Parameter ändern und Antworten in Echtzeit beobachten.

Eine API-Sammlung besteht aus:

• Anfragedefinitionen (Methode, URL, Header, Body)

• Umgebungsvariablen (z. B. Authentifizierungstoken oder Basis-URLs)

• Ordnerstrukturen, die Arbeitsabläufe darstellen (z.B., Auth, Benutzer anlegen, Nachricht senden)

• Inline-Dokumentation

• Testskripte für die Validierung

Warum das traditionelle API-Onboarding zu kurz greift

API-Spezifikationen erzählen, zeigen aber nicht

OpenAPI-Spezifikationen eignen sich hervorragend für die Erstellung von Werkzeugen, die Validierung und die automatisch generierte Dokumentation. Aber sie sind immer noch Entwürfe, keine tatsächlichen Gebäude. Sie definieren, was vorhanden ist, aber nicht, wann oder wie es zu verwenden ist. Sie haben keine Abfolge, keine Erzählung und keinen Kontext.

Dokumentation kann die Absichten der Entwickler nicht vorhersagen

Ein Entwickler, der nur eine "Test-SMS" versenden will, könnte sich in den Tiefen der Tarifgrenzen oder optionalen Felder verlieren, die er noch nicht braucht. Ohne gute Beispiele sind Entwickler auf Vermutungen angewiesen:

• Brauche ich diese Kopfzeile?

• Sollte ich diesen URL-Parameter kodieren?

• Warum erhalte ich eine 401, obwohl mein Token gültig aussieht?

Kein sicherer Spielplatz

Sammlungen bieten eine strukturierte und bearbeitbare Umgebung, in der Entwickler oder Benutzer Arbeitsabläufe testen können, ohne sich Sorgen machen zu müssen, dass sie unbeabsichtigtes Verhalten auslösen.

Vorteile von API-Sammlungen

API-Sammlungen verbessern die Erfahrung von Entwicklern auf greifbare Weise, sowohl für interne als auch für externe Zielgruppen.

Einen Schnellstart anbieten

API-Sammlungen machen Schluss mit dem Problem der leeren Seite. Anstatt bei Null anzufangen, öffnen Entwickler eine Sammlung und sehen sofort:

• Vorausgefüllte Anfragen

• Verwaltete Auth-Variablen

• Klare Struktur für häufige Anwendungsfälle

Dies hilft den Entwicklern, schnell Erfolge zu erzielen und die Entwicklung voranzutreiben.

Interaktives Lernen ermöglichen

API-Sammlungen unterstützen die Erforschung in einer Weise, wie es statische Dokumente nicht können. Sie können z. B. eine "Learning by doing"-Mentalität fördern:

• Was passiert, wenn ich diesen Parameter ändere?

• Kann ich diese Anrufe kombinieren?

• Wie funktioniert die Fehlerbehandlung?

Debugging einschalten

Sammlungen dienen als gemeinsame Sprache für alle Teams:

• Entwickler können fehlgeschlagene Anfragen exportieren

• Support-Techniker können Probleme wiederholen und isolieren

• QA-Teams können Abläufe im Staging validieren

Sichere und wiederholbare Tests ermöglichen

Mit Umgebungsvariablen erleichtern Sammlungen das Überprüfen:

• Lokale Entwicklungsumgebungen

• Staging- oder Sandbox-APIs

• Produktionsumgebungen (sorgfältig)

Die API-Sammlung kann in automatisierten Tests oder zur Validierung von Akzeptanzkriterien bei Code-Reviews verwendet werden.

Verbesserung der teamübergreifenden Kommunikation

Sammlungen helfen verschiedenen Teams bei der Abstimmung des API-Verhaltens. Sie dienen als lebendige Dokumentation, die sich mit dem Produkt weiterentwickelt.

Vertrauen schaffen durch Transparenz

Sammlungen zeigen genau, was gesendet und empfangen wird. Diese Transparenz schafft Vertrauen,8 insbesondere in Unternehmen oder regulierten Umgebungen, wo Transparenz entscheidend ist.

Erstellen und Freigeben von API-Sammlungen

In den folgenden Unterabschnitten finden Sie ein schrittweises Vorgehen für den Aufbau einer effektiven API-Sammlung.

Beginnen Sie mit einem Anwendungsfall, nicht mit Endpunkten

Importieren Sie nicht einfach Ihre OpenAPI-Spezifikation in Postman. Beginnen Sie mit echten Arbeitsabläufen:

• Was sind die häufigsten Aktionen von Entwicklern?

• Was ist das "Hallo, Welt" für Ihre API?

• Wie sieht eine vollständige Reise aus?

Zum Beispiel:

• Testbenutzer anlegen → Anmeldung simulieren → Token generieren

• Senden einer SMS → Abrufen des Nachrichtenstatus

Verwenden Sie ein Tool, das zum technischen Produktstapel passt

Wählen Sie ein Tool, das zu den Arbeitsabläufen Ihres Teams passt - Postman, Bruno, Insomnia oder sogar VS Code REST Client.

Einrichten und Konfigurieren eines neuen Sammelprojekts

Erstellen Sie ein Projekt/einen Arbeitsbereich und fügen Sie hinzu:

1. Eine neue Sammlung (z.B., Kundeneinführungs-API)

2. Ordner für logische Gruppierungen (Auth, Users, Payments)

3. Ersuchen mit:

   1. Beschreibende Namen (Benutzer erstellen, Token holen)Gültige Standardparameter

   2. Kurze Inline-Beschreibungen

Umgebungsvariablen hinzufügen

Ersetzen Sie hart kodierte Werte durch Variablen, zum Beispiel: {{api_key}}, {{base_url}}, und {{access_token}}.

Schaffen Sie Umgebungen für:

• Lokale Entwicklung

• Aufführung

• Produktion

Für den internen Gebrauch können Sie Umgebungskonfigurationen über Arbeitsbereiche gemeinsam nutzen.

Für externe Benutzer sollten Sie Beispielwerte und Einrichtungsanweisungen angeben.

Optional: Fügen Sie Pre-Request-Skripte hinzu, um automatisch Token für OAuth-Flows zu generieren.

Beispielantworten und Tests einbeziehen

Für jede Anfrage:

• Erfolgreiche Beispielantworten hinzufügen

• Gemeinsame Fehlerantworten (401, 403, 500) einbeziehen

• Schreiben von Testskripten zur Validierung von Antworten und zur Extraktion von Werten (wie Token oder IDs), die in nachfolgenden Anfragen wiederverwendet werden können

Versioniert halten

Behandeln Sie Sammlungen wie Code:

• In einem GitHub Repo speichern

• Aktualisierung während der Sprint Reviews

• Version mit Tags oder Zweigen, die an den Versionshinweisen ausgerichtet sind

Auf die richtige Weise teilen

Für externe Kunden

• Veröffentlichen Sie die Sammlung über Public Workspaces oder GitHub

• Fügen Sie eine README mit Anweisungen zur Einrichtung ein

• Bereitstellen einer Basis-Umgebungsvorlage

Für interne Teams

• Speichern in GitHub oder gemeinsamen Arbeitsbereichen

• Anheften an Ihr internes Portal, Notion oder Onboarding-Dokumente

• Verwenden Sie Slack-Bots, um Links zu veröffentlichen, z. B. "Sie müssen die Anmeldung testen? Verwenden Sie die Auth API Collection → [Link]"

Vonage Contact Center API mit Postman Beispiel

Wenn Sie sich in die Vonage Contact Center API integrieren möchten, können Sie dies mit der offiziellen Postman-Sammlung tun. In den folgenden Schritten zeige ich Ihnen, wie der Onboarding-Flow aussieht. So sieht der Onboarding-Flow aus. Sie finden die offizielle Vonage Postman-Sammlung um mehr zu erfahren.

Fork the Collection

In der nachstehenden Abbildung sehen Sie, welche Stammordner in dieser Sammlung enthalten sind:

Root-Level API Folders in Postman Collection

Klicken Sie auf der öffentlichen Postman-Seite auf Fork.

Fork a Postman Collection for Vonage APIs

Arbeitsbereich erstellen/auswählen (z. B. customer-support-dev).

Create Postman workspace from Fork

Einrichten der Umgebung

Schaffen Sie eine neue Umgebung.

Root-Level API Folders in Postman CollectionFügen Sie Variablen wie {{client_id}}, {{client_secret}} und {{region}} .

Vonage Auth Token Request from PostmanWählen Sie diese Umgebung aus dem Dropdown-Menü in Postman aus.

Select Environment in Postman

Authentifizieren Sie

Führen Sie die POST auth/connect/token Anfrage.

Hinweis: Postman füllt die Variablen automatisch mit den Umgebungseinstellungen aus den vorherigen Schritten aus.

Vonage User API GET Request from Postman

Einen echten API-Aufruf durchführen

Führen Sie GET /users aus dem Ordner Users.

Vonage Auth Endpoint Setup in PostmanHerzlichen Glückwunsch, Sie sind authentifiziert und bereit, den Fluss zu testen.

Sie können auch:

• Erweitern mit neuen Ordnern

• Parameter ändern

• Gemeinsame Nutzung durch Ihr Team

• Version zusammen mit dem Code Ihrer Anwendung

Schlussfolgerung

Sie können dies mit automatisierten Tests oder CI-Integrationen erweitern oder die Sammlung an andere Vonage-APIs wie Voice oder Messages anpassen.

Wenn wir das API-Einführung als eine Produkterfahrung behandeln, API-Sammlungen mehr als nur praktisch, sie werden zu einem strategischen Begleiter. Eine sorgfältig erstellte Sammlung von APIs kann:

• Vereinfachen Sie die Ersteinrichtung und die Lernkurve für neue Entwickler.

• Befähigung von Entwicklern, die APIs schnell zu verstehen und effektiv zu nutzen.

• Führen Sie Entwickler durch die vorgesehenen Anwendungsfälle und Funktionen des API-Ökosystems.

Durch die Integration der API-Sammlung in die Dokumentation und die Versionskontrolle können wir eine Umgebung schaffen, in der das Lernen interaktiv ist, das Feedback unmittelbar erfolgt und API-Annahme sich wirklich nahtlos anfühlt.