Verwenden eines Prototyps als API-Produktspezifikation

Veröffentlicht: 2016-02-02

Als Developer Experience Product Manager bei SendGrid habe ich die Aufgabe, Möglichkeiten, Funktionen und Produkte zu identifizieren, die unsere API betreffen. Eine Sache, an der ich gearbeitet habe, ist die Identifizierung von Methoden, um die Kommunikation meiner Produktideen an die anderen PMs, Ingenieure und Kunden effektiver zu gestalten.

Ich habe gelernt, dass ein monolithisches Produktanforderungsdokument (PRD) ein weniger als idealer Weg ist, dies zu tun, und dass eine testbare Schnittstelle, die dieselben Informationen wie eine Produktspezifikation enthält, eine leistungsfähige Alternative wäre. Das Problem mit PRDs ist, dass sie oft sehr groß sind und hauptsächlich Text enthalten. Es ist zu leicht, seinen Platz zu verlieren oder etwas wirklich Wichtiges zu verpassen.

Unsere Freunde in UX haben dieses Problem mit Tools wie Invision gelöst, wo sie eine anklickbare Oberfläche bereitstellen, die Sie berühren und verwenden können, anstatt ein Dokument oder ein Wireframe, das einfach die Oberfläche beschreibt. Da eine API eine Schnittstelle ist, brauchen wir ein Tool, das die Interaktion mit der Spezifikation in Echtzeit ermöglicht, anstatt eine Menge beschreibenden Text und JSON in einem Dokument.

Anforderungen definieren

Wie soll diese testbare Schnittstelle als Produktspezifikation aussehen? Wie würde es funktionieren? Existiert es?

Als ich Kapitel 18, „Reinventing the Product Spec“, von Marty Cagan’s Inspired: How to Build Products Customers Love las, wurde mir klar, dass ich ein von mir verwendetes Tool teilen wollte, das Cagans Anforderungen an eine Produktspezifikation größtenteils erfüllt seine Wunschliste für Produktspezifikationen und meine persönliche Liste mit Prototyp-als-Spezifikation-Anforderungen.

Cagans Anforderungen*:

  • Die Spezifikation muss die vollständige Benutzererfahrung beschreiben.
  • Die Spezifikation muss das Verhalten der Software genau wiedergeben.
  • Sie müssen in der Lage sein, das Produkt so zu kommunizieren, dass alle Beteiligten das bekommen, was sie brauchen.
  • Die Spezifikation wird sich ändern
  • Es muss eine einzige Master-Darstellung der Spezifikation geben, um Mehrdeutigkeit und Versionitis zu reduzieren.

Cagans Wunschliste*:

  • Sie müssen den Prototypen ergänzen [mit]:
    • Geschäftslogik
    • Freigabeanforderungen
    • Plattformbereitstellungsanforderungen
    • Anwendungsfälle
  • Ich möchte wirklich in der Lage sein, den Prototyp zu kommentieren

Meine Anforderungen an Prototyp-als-Spezifikation:

  • Der Prototyp sollte die Spezifikation sein.
  • Die Dokumentation sollte in den Prototyp integriert werden.
  • Jeder im Unternehmen, der ihn benötigt, sollte Zugriff auf den Prototyp und die Dokumentation haben.
  • Der Kunde sollte in der Lage sein, auf den funktionalen Teil des Prototyps für Benutzertests zuzugreifen.
  • Der Prototyp sollte die Spezifikation ersetzen und so nah wie möglich an der beabsichtigten Funktionalität arbeiten, ohne ein fertiges Produkt zu verkabeln.
  • Es sollte einfach sein, Änderungen am Prototyp vorzunehmen und aufzuzeichnen.
  • Es sollte einfach sein, A/B-Variationen zu erstellen, die von jedem getestet werden können, der Zugang zum Prototyp hat.
  • Die Kundendokumentation soll einfach aus dem Prototypen exportiert werden können.

Einführung von StopLight

Das Tool, das ich verwendet habe und das fast alles oben Genannte erfüllt, heißt Stoplight.io . Es ist im Kern eine API-Dokumentations-Engine und ein Web-Proxy. Es ermöglicht Ihnen, Ihre API mithilfe einer intuitiven Benutzeroberfläche zu definieren, die hinter den Kulissen das Beste von Swagger und RAML als Spezifikations-Engine bietet, zusammen mit der Möglichkeit, aus beiden Formaten zu importieren oder zu exportieren.

Da StopLight ein Dokumentationstool ist, können Sie die Anforderungen, Antworten, Header und Beschreibungen für Ihre Endpunkte definieren. Mit der Proxy-Funktion können Sie Ihre API aufrufen und überprüfen, ob Ihre Aufrufe Ihrer Spezifikation entsprechen, oder Ihre Endpunkte automatisch erkennen, um den größten Teil Ihrer Dokumentation automatisch schreiben zu lassen.

Der Proxy von StopLight hat auch einige andere absolut erstaunliche Funktionen:

  • Die Möglichkeit, Scheinanrufe an Ihre Endpunkte zu tätigen, wenn Ihr Produkt noch nicht fertig ist oder Sie Ihre Anfragen nicht per Proxy weiterleiten möchten.
  • Lokaler Server zum Testen Ihres Prototyps auf Ihrer Maschine.
  • Remote-Server zum Testen Ihres Prototyps im Internet.
  • In Javascript geschriebene Middleware zum Definieren von Code, der ausgeführt werden kann, bevor und/oder nachdem die Endpunkte Ihres Prototyps aufgerufen werden.

Wenn Sie die Kombination aus meiner Wunschliste, Cagans Spezifikationsanforderungen und seiner Wunschliste mit der Funktionalität vergleichen, die StopLight bietet, können Sie sehen, dass StopLight alle Bedürfnisse und Wünsche erfüllt:

  • Nur interne Dokumentation des Prototyps und seiner Features.
  • Ein leicht zugänglicher vollständiger Prototyp der Funktionalität.
  • Eine testbare Schnittstelle, die die Möglichkeit bietet, variable Funktionen für Benutzertests und Feedback umzuschalten.
  • Eine einfache Möglichkeit, Ihren Prototyp für ein bestimmtes Gespräch zu versionieren, sodass Sie die Funktionalität des Prototyps nahezu in Echtzeit ändern können, um das erhaltene Feedback zu veranschaulichen und zu überprüfen.

Der Arbeitsablauf in StopLight ist einfach und kann von jedem durchgeführt werden, unabhängig von seinen technischen Fähigkeiten:

  • Erstellen Sie ein neues Projekt.
  • Fügen Sie die Spezifikation hinzu, indem Sie auf klicken und Informationen über den Endpunkt, seine Parameter, Anforderung und Antwort eingeben.
  • Fügen Sie im Definitionsbildschirm die Spezifikationsinformationen zu Ihrem Prototyp hinzu.
  • Wenn Sie über optionale Funktionen verfügen, fügen Sie diese mithilfe der Middleware hinzu.
  • Spott einschalten.
  • Kopieren Sie die öffentliche URL für den Mocking-Server, fügen Sie sie ein und geben Sie sie für Feedback frei.

Wenn Sie zu einem Kundenbesuch gehen und mit dem Prototypen in Echtzeit experimentieren möchten, laden Sie einfach die Definition auf Ihren Computer herunter, erstellen Sie ein neues Projekt, das nach Ihrem Besuch benannt ist, und importieren Sie die Definition. Jetzt können Sie alles ändern, was Sie wollen, ohne Ihren ursprünglichen Prototyp zu ändern. Wenn Sie zurück sind und Ideen zusammenführen, ist es so einfach, Änderungen vorzunehmen, wie es war, den Prototypen überhaupt zu bauen.

Als Developer Experience Product Manager hilft mir StopLight nicht nur, meine Arbeit effizienter zu erledigen, es ist auch absolut einfach zu bedienen und erleichtert die Bereitstellungsvorbereitungsschritte zur Dokumentation der API, da die Dokumentation vor den Schritten der Kundenvalidierung gestartet und aktualisiert wird während des gesamten Prozesses. Es gibt viele andere Anwendungsfälle und Funktionen, die StopLight bietet, aber dies hat sich möglicherweise am stärksten auf meine Arbeit ausgewirkt.

*Cagans Anforderungen und Wunschliste sind direkte Zitate aus Inspired: How to Build Products Customers Love.