Product
Mailgun Hack Day: Unsere API-Dokumentation wird intelligenter
Jeden Monat hat unser Team die Gelegenheit, an den Projekten zu arbeiten, auf die wir gerade Lust haben. Eine großartige Möglichkeit, etwas Neues zu lernen, mit verschiedenen Teammitgliedern zusammenzuarbeiten oder einfach nur Dinge aufzuräumen, die uns schon länger stören.
Für den Hack Day im Januar widmeten sich einige von uns (Anton, Jesse und ich) der Verbesserung unserer API-Dokumentation.
Das Problem
Unsere API ist gut dokumentiert und bietet eine große Auswahl an Codebeispielen für alle gängigen Programmiersprachen. Allerdings sind uns einige Dinge beim Workflow aufgefallen.
Um eine API-Anfrage auszuprobieren, geht man typischerweise wie folgt vor:
- ein Codebeispiel in einen Texteditor kopieren
- einige Parameter bearbeiten (z. B. Absenderadresse, Empfängeradresse, Text)
- zum Mailgun Control Panel wechseln, um den API-Schlüssel zu kopieren
- zum Code-Editor zurückkehren und den Schlüssel einfügen
- das Beispiel in die Befehlszeile kopieren und ausführen
Um schnell einen neuen Dienst zu erkunden oder einen neuen Endpunkt zu testen, scheinen das ein paar Schritte zu viel zu sein.
Die Lösung
Teil 1: Ihre Mailgun-Einstellungen in Codebeispielen
Jetzt sind die angezeigten Codebeispiele etwas intelligenter. Wenn Sie bei Mailgun eingeloggt sind, fügen wir Ihren API-Schlüssel und einige intelligente Standardwerte für Sie ein.
Sie fügen die Codebeispiele also einfach in Ihre Befehlszeile ein, führen sie aus und sie funktionieren auf Anhieb.
Teil 2: Codebeispiele lassen sich im Browser bearbeiten
Zudem lassen sich die Codebeispiele jetzt direkt bearbeiten. Dank des Ace-Editors verwandelt ein Klick jedes Codebeispiel in einen kleinen In-Browser-Texteditor, in dem Sie Änderungen vornehmen können.
Fazit
Die API-Dokumentation ist entscheidend für das Nutzungserlebnis eines Dienstes für Softwareentwicklung. Da die oben genannten Änderungen nun live sind, hoffen wir, dass das Ausprobieren unserer API für alle, die unseren Dienst neu erkunden, sowie für bestehende Teams, die verschiedene API-Endpunkte testen oder Fehler beheben möchten, deutlich einfacher wird.
