Das Problem mit API-Schlüsseln, die nie ablaufen
Ein Schlüssel, der vor Jahren ausgestellt, nie rotiert wurde und heute noch gültig ist, ist keine Bequemlichkeit. Er ist ein Risiko, das sich seit Jahren niemand mehr angesehen hat.
Warum die Qualität der Dokumentation wichtiger ist als die Zahl der Funktionen
Eine Preisseite mit vierzig Endpunkten wirkt leistungsfähiger als eine mit fünfzehn. Oft ist sie aber auch ein Warnsignal. Einen Endpunkt zu bauen, ist nur ein Bruchteil der Arbeit, die nötig ist, um ihn nutzbar zu machen. Der Rest ist Dokumentation: klare Parameterbeschreibungen, echte Beispielanfragen und -antworten, ehrliche Hinweise zu Grenzfällen und eine verständliche Erklärung, was passiert, wenn etwas schiefgeht. Lassen Sie diese Arbeit bei vierzig Endpunkten weg, und Sie erhalten vierzig Funktionen, die technisch existieren und praktisch kaum.
Wir haben lieber weniger Dinge gut dokumentiert als mehr Dinge schlecht. Ein Entwickler, der eine API bewertet, liest selten zuerst die Funktionsliste. Er liest die Dokumentation, probiert eine Beispielanfrage aus und bildet sich innerhalb der ersten Minuten eine Meinung über das ganze Unternehmen, je nachdem, ob dieses Beispiel tatsächlich so funktioniert, wie es geschrieben steht. Wenn nicht, spielt die Anzahl der Funktionen auf der Marketingseite keine Rolle mehr, denn das Vertrauen, das nötig ist, um weiterzulesen, ist gerade verschwunden.
Gute Dokumentation bedeutet für uns ein paar konkrete Dinge und kein vages Versprechen. Sie bedeutet, dass die Authentifizierung mit jeder akzeptierten Methode verständlich erklärt wird und nicht nur mit der, die der Anbieter bevorzugt. Sie bedeutet, dass Ratenlimits als echte Zahlen angegeben werden und nicht als „es gelten großzügige Limits“. Sie bedeutet, dass Fehlercodes zusammen mit ihrer tatsächlichen Ursache aufgeführt werden, sodass ein Entwickler, der eine fehlgeschlagene Anfrage debuggt, die Antwort in der Dokumentation findet, statt allein anhand eines Statuscodes zu raten. Nichts davon erfordert mehr Entwicklungsarbeit. Es erfordert, dass jemand entscheidet, dass eine klare schriftliche Darstellung keine optionale Fleißarbeit neben dem eigentlichen Produkt ist.
Eine Dokumentation, die nur ausreichend ist, verursacht außerdem Kosten, die sich summieren. Ein Entwickler, der in der Dokumentation keine Antwort findet, eröffnet ein Support-Ticket, und nun kostet die Lösung dieser einen Frage Arbeitszeit von Mitarbeitern, zusätzlich zur Entwicklungszeit, die bereits in die Funktion geflossen ist. Multiplizieren Sie das mit genügend Kunden, die über denselben unklaren Absatz stolpern, und die „Einsparungen“ durch dünne Dokumentation werden schnell negativ. Klare Dokumentation ist kein nettes Extra obendrauf auf die API. Sie ist günstiger als die Alternative, sobald man die Supportlast mitrechnet, die ein unklarer Absatz erzeugt.
Wir glauben auch, dass die Qualität der Dokumentation eines der wenigen Signale ist, die ein potenzieller Kunde tatsächlich bewerten kann, bevor er sich auf eine Integration festlegt. Die Verfügbarkeitshistorie eines Anbieters können Sie nicht so einfach in fünf Minuten prüfen, und die Datengenauigkeit können Sie ohne vorherige Integration nicht vollständig beurteilen. In fünf Minuten können Sie aber die Dokumentation lesen und beurteilen, ob das Unternehmen, das sie geschrieben hat, das Produkt gut genug verstanden hat, um es verständlich zu erklären, oder ob sie sich liest wie ein nachträglich angeschraubter Zusatz zu einer Funktionsliste, die für eine Verkaufsseite gebaut wurde.
Eine lange Funktionsliste ist schnell geschrieben. Eine Dokumentation, mit der ein Entwickler beim ersten Versuch tatsächlich etwas bauen kann, ist es nicht, und genau dieser Unterschied ist der Grund, warum sie wichtiger ist.