Befreien Sie sich vom Alleingang: Lernen Sie, mit Postman bei der API-Entwicklung zusammenzuarbeiten

Die API-Entwicklung ist ein großer Teil dessen, was ich an Software liebe. Ob es darum geht, Integrationen zu erstellen oder APIs für entkoppelte Webanwendungen zu erstellen, normalerweise sind es nur ich und der Code .

Die meiste Zeit arbeite ich als Solo-API-Entwickler. Alleine unterwegs zu sein hat seine Vorteile: schnelle Entscheidungen und volle Kontrolle. Aber es ist ein zweischneidiges Schwert, denn alles im Kopf zu behalten macht Übergaben und Delegationen schwierig. Und wenn ich alleine arbeite, schränkt dies die Größe und Komplexität der Projekte ein, an denen ich arbeiten kann. Schließlich bin ich nur eine Person.

Postman ist mein Hauptwerkzeug für die API-Arbeit – das Senden von Anfragen, das Verwalten von Umgebungen und das Ausführen von Tests. Ich bin mit meinem Solo-Workflow vertraut. Aber ich habe mich gefragt: Was kann Postman in einer Teamumgebung noch mehr bieten? Wie könnte es die Zusammenarbeit verbessern und den Entwicklungsprozess rationalisieren?

Um diese Fragen zu untersuchen, begann ich mit der Arbeit an einer Beispiel-API, die ich „X Nihilo“ nenne.

Beispiel-API: X Nihilo

Mit X Nihilo können Sie Tweets mit 280 Zeichen basierend auf den von Ihnen gespeicherten oder gesendeten Parametern erstellen. Sie geben ein Thema, ein Ziel, eine Beschreibung des Tons und eine Beschreibung der Zielgruppe an. Hinter den Kulissen sendet die API eine Anfrage zur Textvervollständigung an die OpenAI-API, die bei der Erstellung des Tweets hilft.

Darüber hinaus können Sie die Zeichenfolgen, die Sie für Ton und Publikum verwenden, speichern und sie dann in nachfolgenden Tweet-Anfragen wiederverwenden.

Lassen Sie uns meinen grundlegenden API-Entwicklungsworkflow durchgehen.

Im Alleingang: mein Solo-Workflow

Der erste Schritt in meinem Workflow besteht darin, die API zu entwerfen und eine OpenAPI-Spezifikation zu verfassen. In Postman habe ich eine neue API erstellt und dann eine neue API-Definition gestartet.

Nach einigem Nachdenken (und der direkten Arbeit mit ChatGPT, was sich hervorragend zum Generieren einer ersten OpenAPI-Spezifikation basierend auf meinen Beschreibungen eignete), ließ ich meine Spezifikation schreiben:

Nachdem ich meine OpenAPI-Spezifikation installiert hatte, kam ich an eine Weggabelung. Sollte ich einen Scheinserver und einige Beispielanfragen und -antworten einrichten, um zu zeigen, wie die Interaktion mit dieser API aussehen würde? Oder sollte ich anfangen, Implementierungscode zu schreiben?

Als Einzelentwickler kann ich zu einem bestimmten Zeitpunkt nur API-Produzent oder API-Konsumer sein. Also entschied ich: Es ist nicht nötig, Nachbildungen zu bauen – der Verbraucher in mir würde warten müssen. Lasst uns etwas Code schreiben!

Ein paar Momente später…

Durch die Verwendung von Node.js mit Express und die Kommunikation mit einer PostgreSQL-Datenbank konnte ich meine grundlegende API implementieren. Hier ist eine Übersicht über alles, was ich zum Bauen brauchte:

• POST /signin nimmt einen username und password , authentifiziert sich anhand von Datensätzen in der Datenbank und gibt dann ein signiertes JWT zurück, das in allen nachfolgenden Anfragen verwendet werden kann.
• POST /generateTweet generiert einen Tweet mit maximal 280 Zeichen. Es braucht ein topic (String) und ein goal (String). Es benötigt außerdem entweder einen tone (String) oder eine toneId (Ganzzahl-ID eines gespeicherten Tons) sowie entweder eine audience (String) oder eine audienceId (Ganzzahl-ID eines gespeicherten Publikums). Immer wenn tone und/oder audience bereitgestellt werden, speichert die API diese in der Datenbank.
• GET /tones gibt eine Liste von Ton-IDs und entsprechenden Zeichenfolgen zurück. GET /audiences macht dasselbe für wiederverwendbare Zielgruppenzeichenfolgen.
• DELETE /tones nimmt eine Ton-ID und löscht diesen Toneintrag. DELETE /audiences bewirkt dasselbe für Publikumsdatensätze.

Nachdem die erste Implementierung abgeschlossen war, war es an der Zeit, zu Postman zurückzukehren und mit der Ausführung einiger Anfragen zu beginnen.

Erstellen Sie eine Umgebung mit Variablen.

Zuerst habe ich eine neue Umgebung namens „Test“ erstellt. Ich habe Variablen hinzugefügt, um meine root_url zusammen mit einem gültigen username und password zu speichern.

Erstellen Sie eine Sammlung und eine Anfrage

Dann habe ich eine neue Sammlung erstellt und meine erste Anfrage hinzugefügt: eine POST Anfrage an /signin , um die Authentifizierung auszuprobieren.

Während mein API-Server in einem Terminalfenster ausgeführt wurde, habe ich meine erste Anfrage gesendet.

Erfolg! Ich habe meinen Token erhalten, den ich bei zukünftigen Anfragen benötigen würde.

Ich habe eine neue Anfrage erstellt, diesmal um einen Tweet zu generieren.

Ich habe darauf geachtet, dass die Autorisierung auf die Verwendung von „Bearer Token“ eingestellt ist, und ich habe das Token bereitgestellt, das ich gerade aus der vorherigen Anfrage erhalten habe.

Hier ist die Antwort:

Es klappt!

Zusammenfassung des Solo-Ansatzes

Das ist ein einfacher Einblick in meinen Solo-Workflow. Natürlich würde ich nebenbei noch ein paar andere Dinge tun:

• Schreiben Sie ein Pre-Request-Skript, um eine /signin Anfrage auszuführen und legen Sie dann eine Umgebungsvariable basierend auf dem Token in der Antwort fest.
• Erstellen Sie Anfragen für alle anderen Endpunkte in der OpenAPI-Spezifikation.
• Schreiben Sie Tests für jeden Endpunkt und achten Sie dabei darauf, meine Randfälle abzudecken.

Wenn ich alleine arbeite, bringt mich dieser grundlegende Arbeitsablauf ziemlich nah an die Ziellinie. Das ist zwar in Ordnung, aber ich weiß , dass ich wahrscheinlich nur an der Oberfläche der verfügbaren Funktionen in Postman kratze. Und ich weiß, dass ich viel mehr von Postman brauchen würde, wenn ich in einem Team arbeiten würde.

Der Aha-Moment: Warum Postman für Teams in Betracht ziehen?

Was wäre, wenn ich nicht länger alleiniger API-Entwickler für X Nihilo sein könnte? Dies kann aus mehreren Gründen passieren:

• X Nihilo nimmt an Größe und Komplexität zu und ein einzelner API-Entwickler reicht nicht mehr aus, um es zu unterstützen.
• X Nihilo ist nur ein kleiner Teil eines größeren API-Projekts, an dem mehrere API-Entwickler oder vielleicht sogar mehrere API-Teams beteiligt sind.

Nicht alle meiner API-Projekte für Kunden sind kleine Projekte, die ich selbst erstellen kann. Manchmal muss ich Teil eines Teams sein, das eine API erstellt. Möglicherweise muss ich sogar das API-Team leiten.

Wenn das passiert, müsste ich meine Solo-Denkweise hinter mir lassen und meine Solo-Art, Dinge in Postman zu erledigen, aufgeben. Das motivierte mich, einen Blick auf die teambezogenen Funktionen von Postman zu werfen.

Entdecken Sie die Funktionen des Postman-Teams (Unternehmen).

Postman verfügt über eine kostenlose Stufe und bietet einige eingeschränkte Funktionen für die Zusammenarbeit, die möglicherweise ausreichen, wenn Sie ein kleines Team sind (d. h. nicht mehr als drei Entwickler). Postman bietet im Rahmen seiner Enterprise Essentials-Stufe zusätzliche Funktionen. Diese eignen sich hervorragend für API-Teams in größeren Organisationen, die Postman flächendeckend nutzen.

Gemeinsame Nutzung des Arbeitsbereichs

Ein Arbeitsbereich ermöglicht Ihren Teams die Zusammenarbeit an mehreren API-Projekten. Das ist großartig, wenn verschiedene Teams an unterschiedlichen APIs arbeiten, diese APIs jedoch miteinander interagieren (was normalerweise in größeren Softwareunternehmen der Fall ist).

Arbeitsbereiche eignen sich hervorragend für die Zusammenarbeit in Echtzeit. Teammitglieder können die API-Dokumentation bearbeiten, gemeinsam Anfragen erstellen oder Tests schreiben und einen Scheinserver erstellen, den das gesamte Team nutzen kann. Wenn Änderungen vorgenommen werden, werden diese in Echtzeit mit dem gesamten Team synchronisiert.

Versionskontrolle

Obwohl mir die Versionskontrolle meines Codes am Herzen lag, war mir als Solo-API-Entwickler die Versionskontrolle meiner Postman-Sammlungen oder -Umgebungen egal. Wenn ich etwas ändere (eine Anfrage ändern, einen Test aktualisieren, eine Umgebungsvariable entfernen), bin ich der Einzige, der davon betroffen ist. Keine große Sache.

Wenn Sie in einem Team arbeiten, möchten Sie unbedingt wissen, wann sich etwas ändert. Und manchmal müssen Sie Änderungen rückgängig machen. Glücklicherweise bietet Postman Teams, die Postman Enterprise verwenden, Zugriff auf ein Änderungsprotokoll für Sammlungen, Arbeitsbereiche und APIs. Sie können Sammlungen auf frühere Zeitpunkte zurücksetzen. Als API-Entwickler in einem Team benötigen Sie dies. Meistens liegt es daran, dass Bob die Sammlung vermasselt hat. Manchmal bist du jedoch Bob.

Rollenbasierter Zugriff und Benutzerorganisation

Nicht jeder in einem Postman-Arbeitsbereich sollte über die gleichen Berechtigungen verfügen. Einige Teammitglieder sind Tester und benötigen lediglich die Fähigkeit, Anfragen zu senden und Tests auszuführen – aber nicht, sie zu ändern. Andere könnten Designer sein, die nur API-Definitionen ändern dürfen.

In Postman können Sie Teammitgliedern Rollen zuweisen. Dies wirkt sich auf die Art des Zugriffs und die Berechtigungsstufe aus, die jedes Teammitglied innerhalb eines Teams oder Arbeitsbereichs hat.

Teams können auch private Arbeitsbereiche haben, wodurch der Zugriff für andere Personen außerhalb des Teams eingeschränkt wird.

Mir ist auch aufgefallen, dass Postman Enterprise „Domain Capture“ unterstützt. Das bedeutet im Grunde, dass Sie alle Benutzer in Ihrer Organisation einrichten können, indem Sie jedem Zugriff über die Domäne (z. B.) mycompany.biz gewähren.

Inline-Kommentare und Diskussionen

Postman verfügt über eine Kollaborationsfunktion, die in allen Plänen verfügbar ist, nicht nur in den Enterprise Essentials. Dies ist die Möglichkeit für Teammitglieder, Kommentare zu Sammlungen hinzuzufügen (zu Ordnern, Anfragen, Beispielen oder Pull-Anfragen). Die Möglichkeit, direkt in Postman Kommentare abzugeben und zu diskutieren, ist für die Team-API-Entwicklung von enormer Bedeutung. Da der Großteil der API-Entwicklungsarbeit Ihres Teams in Postman stattfinden wird, ist es sinnvoll, Ihre Diskussion dort zu führen (statt in GitHub oder einem anderen externen Dienst).

Team API-Entwicklung: Postman für den Sieg

Wann immer ich einem Team beitrete, bringe ich die Tools mit, die ich gerne verwende, aber ich dränge sie meinen Teamkollegen nicht wirklich auf. Ich denke, sie haben ihre eigenen Werkzeuge. Also jedem das Seine. Aber ich habe das Gefühl, dass die meisten API-Entwickler Postman in ihrem Werkzeuggürtel haben. Es wäre einfach eine Schande, wenn mehrere API-Entwickler in einem Team Postman einzeln nutzen würden, mit einer Solo-Denkweise und ohne einige dieser Teamfunktionen zu nutzen. Wenn sie die Funktionen von Postman Enterprise nutzen würden, würden sie …

Erhöhte Effizienz

In einem gemeinsam genutzten Arbeitsbereich können Sie mit der Definition der gemeinsam genutzten API beginnen. Immer wenn ein Teammitglied die Definition (oder Dokumentation, Tests oder Umgebungen) bearbeitet, werden die Änderungen synchronisiert und jeder verfügt über die neuesten und besten Informationen.

Jeder bearbeitet die gleichen Anforderungen in einer Sammlung und jeder hat Zugriff auf alle Tests, die verwendet werden. All diese Annehmlichkeiten verbessern die Effizienz eines Teams, was wiederum seine Entwicklungsgeschwindigkeit in die Höhe schnellen lässt.

Weniger Missverständnisse

Wenn alle mit derselben Quelle der Wahrheit (Ihrem Arbeitsbereich) arbeiten und innerhalb des Tools, das sie für die Entwicklung verwenden, Kommentare abgeben und sich unterhalten können, führt dies zu weniger Missverständnissen. Ihr Team wird keine Zeit mit Verwirrung darüber verlieren, ob dieser Endpunkt Abfrageparameter oder Pfadparameter annehmen sollte. Alles wird klar sein.

Schlüssel zum Mitnehmen

Ich wusste nicht, dass Postman für Teams und Unternehmen gedacht ist. Jetzt, wo ich es weiß, ist hier meine wichtigste Erkenntnis: Teamplayer nutzen Werkzeuge, die gut für das Team sind.

Als Solo-API-Entwickler hat sich Postman für mich als großartig erwiesen. Glücklicherweise verfügt es auch über Funktionen, die es für mich großartig machen würden, wenn ich in einem API-Entwicklerteam bin. Für mich bedeutet das die Echtzeitsynchronisierung von Bearbeitungen innerhalb von Sammlungen, Änderungsprotokollen und Versionskontrolle sowie detaillierte Zugriffsberechtigungen. Jetzt freue ich mich darauf, größere API-Projekte mit größeren Teams zu übernehmen.

Viel Spaß beim Codieren!

Auch hier veröffentlicht.