5 goldene Regeln für großartiges Web-API-Design

Haben Sie sich jemals gefragt : „Was haben sie sich dabei gedacht?“ bei der Einbindung eines Webservices über seine API? Wenn nicht, hast du viel mehr Glück gehabt als ich.

Jeder Softwareentwickler weiß, wie einfach es ist, ein Projekt zu Spaghetti-Code werden zu lassen, und Web-APIs sind nicht weniger anfällig für ein Wirrwarr. Aber es muss nicht so sein. In Wahrheit ist es möglich, großartige Web-APIs zu entwerfen, die die Leute gerne verwenden und die Sie auch gerne erstellen. Aber wie? Um die Antwort auf diese Frage geht es in diesem Beitrag.

Perspektive

Wenn Sie Lösungen erstellen, entwerfen Sie die meiste Zeit für Endbenutzer, die keine Programmierer sind oder die im Allgemeinen technisch nicht versiert sind. Sie geben ihnen eine grafische Benutzeroberfläche, und wenn Sie Ihre Arbeit richtig gemacht haben, haben Sie von ihnen eine ziemlich gute Vorstellung davon bekommen, wozu sie die Benutzeroberfläche benötigen.

Aber die API-Entwicklung ist anders. Sie entwerfen eine Schnittstelle für Programmierer , wahrscheinlich ohne zu wissen, wer sie sind. Und wer auch immer sie sind, sie werden die technische Raffinesse haben (oder zumindest glauben, dass sie die technische Raffinesse haben), um auf jeden kleinen Fehler in Ihrer Software hinzuweisen. Ihre Benutzer stehen Ihrer API wahrscheinlich genauso kritisch gegenüber wie Sie ihrer eigenen und werden es sehr genießen, sie zu kritisieren.

Und darin liegt übrigens ein Teil der Ironie. Wenn jemand verstehen sollte, wie man eine benutzerfreundliche Web-API erstellt, dann Sie . Schließlich sind Sie genau wie die Benutzer Ihrer API ein Softwareentwickler, also teilen Sie ihre Perspektive. Nicht wahr?

Nun, während Sie sicherlich ihre Perspektive verstehen , teilen Sie ihre Perspektive nicht unbedingt. Wenn Sie Ihre API entwickeln oder verbessern, haben Sie die Perspektive eines API- Designers, während sie die Perspektive eines API- Benutzers haben .

API-Designer konzentrieren sich normalerweise auf Fragen wie „Was muss dieser Dienst tun?“. oder "Was muss dieser Dienst bieten?" , während sich API-Benutzer auf „Wie kann ich diese API verwenden, um das zu tun, was ich brauche?“ konzentrieren. , oder genauer gesagt: „Wie kann ich das Nötigste an Aufwand aufwenden, um aus dieser API das herauszuholen, was ich brauche?“ .

Diese unterschiedlichen Fragen führen zu zwei sehr unterschiedlichen Perspektiven. Daher ist die notwendige Voraussetzung für das Entwerfen einer großartigen API, Ihre Perspektive von der des API-Designers auf die des API-Benutzers zu verlagern. Mit anderen Worten, stellen Sie sich immer wieder die Fragen, die Sie selbstverständlich stellen würden, wenn Sie Ihr eigener Benutzer wären. Anstatt darüber nachzudenken, was Ihre API leisten kann , denken Sie über die verschiedenen Möglichkeiten nach, wie sie möglicherweise verwendet werden muss oder möchte, und konzentrieren Sie sich dann darauf, diese Aufgaben für die Benutzer Ihrer API so einfach wie möglich zu gestalten.

Auch wenn dies einfach und offensichtlich klingen mag, ist es erstaunlich, wie selten APIs so gestaltet zu sein scheinen. Denken Sie an die APIs, denen Sie in Ihrer Karriere begegnet sind. Wie häufig scheinen sie mit dieser Perspektive entworfen worden zu sein? Das Design von Web-APIs kann eine Herausforderung darstellen.

Lassen Sie uns also fortfahren und über die 5 goldenen Regeln für das Entwerfen einer großartigen Web-API sprechen, nämlich:

1. Dokumentation
2. Stabilität und Konsistenz
3. Flexibilität
4. Sicherheit
5. Einfache Annahme

Regel 1: Dokumentation

Dokumentation. Ja, ich fange hier an.

Hassen Sie Dokumentation? Nun, ich kann nachfühlen, aber setzen Sie Ihren „Benutzerperspektiven“-Hut auf und ich wette, dass das einzige, was Sie mehr hassen, als Dokumentation schreiben zu müssen, der Versuch ist, eine undokumentierte API verwenden zu müssen. Ich lasse meinen Fall.

Das Fazit ist, dass Dokumentation unerlässlich ist, wenn Sie möchten, dass jemand Ihre API verwendet. Das muss man einfach richtig machen. Es ist das erste, was Benutzer sehen werden, also ist es in gewisser Weise wie die Geschenkverpackung. Präsentieren Sie sich gut, und die Leute werden Ihre API eher verwenden und alle Eigenheiten in Kauf nehmen.

Wie schreiben wir also eine gute Dokumentation?

Der relativ einfache Teil besteht darin, die API-Methoden selbst zu dokumentieren; dh Beispielanfragen und -antworten, zusammen mit Beschreibungen jedes der Elemente in beiden. Glücklicherweise gibt es immer mehr Softwaretools, die die Dokumentationserstellung erleichtern und vereinfachen. Oder Sie können selbst etwas schreiben, das Ihre API, Endpunkte und Funktionen überprüft und die entsprechende Dokumentation für Sie generiert.

Aber was eine großartige Dokumentation von einer angemessenen Dokumentation unterscheidet, ist die Einbeziehung von Anwendungsbeispielen und idealerweise Tutorials. Dies hilft dem Benutzer, Ihre API zu verstehen und wo er anfangen soll. Es orientiert sie und hilft ihnen, Ihre API in ihr Gehirn zu laden.

Zum Beispiel, wenn die Entwickler von Twilio jede Klasse, jede Methode und jede mögliche Antwort auf ihre API auflisten würden, aber nicht erwähnen würden, dass Sie eine SMS senden, einen Anruf verfolgen oder eine Telefonnummer kaufen können ihrer API, würde es sehr lange dauern, bis der API-Benutzer diese Informationen findet und zusammenhängend versteht. Können Sie sich vorstellen, einen riesigen Baum von Klassen und Methoden zu durchsuchen, ohne zu wissen, wofür sie verwendet wurden, abgesehen von ihrem Namen? Klingt schrecklich, oder? Aber genau das tun so viele API-Anbieter und lassen ihre APIs damit für niemanden außer sich selbst undurchsichtig. Der Rackspace CloudFiles Entwickler- und API-Leitfaden ist ein solches Beispiel; Es ist schwierig, sich zu orientieren, wenn Sie nicht bereits verstehen, was sie tun und was sie anbieten.

Schreiben Sie also kurze Tutorials, die dem Entwickler helfen, schnell einsatzbereit zu sein, mit zumindest einem Grundgerüst dessen, was er zu tun versucht, und weisen Sie ihn dann auf die detailliertere, vollständig dokumentierte Liste der Funktionen hin, damit er sie erweitern kann auf das, was sie haben.

Wenn Sie mit Ihrer Dokumentation fertig sind, stellen Sie sicher, dass sie für andere Personen als Sie selbst sinnvoll ist. Senden Sie es an andere Entwickler in Ihrem Netzwerk, geben Sie ihnen keine anderen Anweisungen, als sie auf die Dokumentation zu verweisen, und bitten Sie sie, einem Tutorial zu folgen oder in etwa 15 Minuten etwas wirklich Grundlegendes zu erstellen. Wenn sie in 15 Minuten keine grundlegende Integration mit Ihrer API haben, haben Sie mehr Arbeit zu erledigen.

Einige bemerkenswerte Beispiele für hervorragende und detaillierte Dokumentation finden Sie unter Twilio, Django und MailChimp. Keines dieser Produkte ist notwendigerweise das beste auf seinem Markt (obwohl es allesamt gute Produkte sind), dennoch zeichnen sie sich dadurch aus, dass sie einige der besten Dokumentationen auf ihren Märkten bereitstellen, was sicherlich ihre breite Akzeptanz und ihren Marktanteil erleichtert hat.

Regel 2: Stabilität und Konsistenz

Wenn Sie jemals die API von Facebook verwendet haben, wissen Sie, wie oft sie ihre APIs ablehnen und komplett neu schreiben. Egal, wie sehr Sie ihre Hackerkultur oder ihr Produkt respektieren, ihre Perspektive ist nicht entwicklerfreundlich. Der Grund, warum sie immer noch erfolgreich sind, ist, dass sie eine Milliarde Benutzer haben, nicht weil ihre API großartig ist.

Aber Sie haben wahrscheinlich nicht den Luxus einer so riesigen Benutzerbasis und eines solchen Marktanteils, also brauchen Sie eine viel weniger volatile API, die alte Versionen am Laufen hält und für einen ziemlich langen Zeitraum unterstützt. Vielleicht sogar Jahre. Zu diesem Zweck finden Sie hier einige Tipps und Tricks.

Nehmen wir beispielsweise an, dass Ihre API über die URL http://myapisite.com/api/widgets erreichbar ist und ihre Antwort im JSON-Format bereitstellt. Dies mag auf den ersten Blick in Ordnung erscheinen, aber was passiert, wenn Sie das Format der JSON-Antwort ändern müssen? Jeder, der bereits mit dir integriert ist, wird zusammenbrechen. Hoppla.

Planen Sie also etwas voraus und versionieren Sie Ihre API von Anfang an, indem Sie explizit eine Versionsnummer in die URL einbauen (z. B. http://myapisite.com/api/widgets?version=1 oder http://myapisite.com/api/widgets/v1 ), damit sich die Leute darauf verlassen können, dass Version 1 funktioniert, und auf jede nachfolgende Version upgraden können, wenn sie dazu bereit sind. Wenn Sie irgendwann eine frühere Version auslaufen lassen müssen, tun Sie dies, aber geben Sie rechtzeitig Bescheid und bieten Sie eine Art Übergangsplan an.

Ein gutes URL-Schema enthält Hauptversionen in der URL. Jede Änderung des Ausgabeformats oder der unterstützten Datentypen sollte zu einer Aktualisierung auf eine neue Hauptversion führen. Im Allgemeinen ist es akzeptabel, dieselbe Version beizubehalten, wenn Sie nur Schlüssel oder Knoten zu Ihrer Ausgabe hinzufügen, aber um auf der sicheren Seite zu sein, sollten Sie jedes Mal, wenn sich die Ausgabe ändert, eine Version erhöhen.

APIs müssen nicht nur im Laufe der Zeit stabil sein, sondern auch intern konsistent sein. Ich habe viele APIs gesehen, die Parameternamen oder Methoden zum Posten von Daten ändern, je nach verwendetem Endpunkt. Stattdessen sollten Sie gemeinsame Parameter global innerhalb Ihrer API behandeln und Vererbung oder eine gemeinsam genutzte Architektur verwenden, um die gleichen Namenskonventionen und die gleiche Datenverarbeitung konsistent in Ihrer gesamten API wiederzuverwenden.

Schließlich müssen Sie ein Änderungsprotokoll aufzeichnen und veröffentlichen, um die Unterschiede zwischen den Versionen Ihrer API aufzuzeigen, damit die Benutzer genau wissen, wie sie ein Upgrade durchführen.

Regel 3: Flexibilität

Garbage in, Garbage out (GIGO) ist ein bekanntes Mantra für die meisten Programmierer. Auf das Web-API-Design angewendet, diktiert dieses Leitprinzip tendenziell einen ziemlich starren Ansatz für die Anforderungsvalidierung. Klingt toll, oder? Kein Durcheinander, kein Problem.

Doch wie bei allem muss es ein gewisses Gleichgewicht geben. Da es nicht möglich ist, jede Art und Weise vorherzusehen, wie Benutzer Ihren Dienst nutzen möchten, und da nicht jede Client-Plattform konsistent ist (dh nicht jede Plattform hat eine sehr gute JSON-Unterstützung, eine anständige OAuth-Bibliothek usw.), ist es gut, dies zu tun haben Sie zumindest ein gewisses Maß an Flexibilität oder Toleranz in Bezug auf Ihre Eingabe- und Ausgabebeschränkungen.

Beispielsweise unterstützen viele APIs eine Vielzahl von Ausgabeformaten wie JSON, YAML, XML usw. al., unterstützt aber nur die Angabe des Formats in der URL selbst. Um flexibel zu bleiben, könnten Sie dies auch in der URL angeben (z. B. /api/v1/widgets.json ) oder Sie könnten auch einen Accept: application/json HTTP-Header lesen und erkennen oder eine unterstützen querystring-Variable wie ?format=JSON usw.

Und wo wir gerade dabei sind, warum nicht zulassen, dass das angegebene Format die Groß-/Kleinschreibung nicht beachtet, damit der Benutzer auch ?format=json angeben kann? Das ist ein klassisches Beispiel dafür, wie unnötige Frustrationen für den Benutzer Ihrer API abgebaut werden können.

Ein weiteres Beispiel ist die Möglichkeit, verschiedene Arten der Eingabe von Variablen zuzulassen. So wie Sie eine Vielzahl von Ausgabeformaten haben, lassen Sie also auch eine Vielzahl von Eingabeformaten zu (z. B. einfache POST-Variablen, JSON, XML usw.). Sie sollten zumindest Standard-POST-Variablen unterstützen, und viele moderne Anwendungen unterstützen auch JSON, also sind diese beiden ein guter Ausgangspunkt.

Der Punkt hier ist, dass Sie nicht davon ausgehen sollten, dass jeder Ihre technischen Vorlieben teilt. Mit ein wenig Recherche darüber, wie andere APIs funktionieren, und durch den Dialog mit anderen Entwicklern können Sie andere wertvolle Alternativen finden, die nützlich sind, und sie in Ihre API aufnehmen.

Regel 4: Sicherheit

Sicherheit ist offensichtlich eines der wichtigsten Dinge, die Sie in Ihren Webdienst einbauen sollten, aber so viele Entwickler machen es lächerlich schwierig, ihn zu verwenden. Als API-Anbieter sollten Sie brauchbare Beispiele für die Authentifizierung und Autorisierung beim Zugriff auf Ihre API anbieten. Dies sollte kein schwieriges Problem sein, an dem ein Endbenutzer stundenlang arbeitet. Machen Sie es sich zum Ziel, dass sie entweder keinen Code schreiben müssen oder weniger als 5 Minuten brauchen, um ihn zu schreiben.

Für die meisten APIs bevorzuge ich eine einfache Token-basierte Authentifizierung, bei der das Token ein zufälliger Hash ist, der dem Benutzer zugewiesen wird, und er kann ihn jederzeit zurücksetzen, wenn er gestohlen wurde. Lassen Sie zu, dass das Token über POST oder einen HTTP-Header übergeben wird. Beispielsweise könnte (und sollte) der Benutzer ein SHA-1-Token als POST-Variable oder als Header in einem Format wie „Authorization: da39a3ee5e6b4b0d3255bfef95601890afd80709“ senden.

Wählen Sie außerdem ein sicheres Token und keine kurze numerische Kennung. Etwas Unumkehrbares ist am besten. Beispielsweise ist es relativ einfach, während der Benutzererstellung einfach ein SHA-Token zu generieren und in der Datenbank zu speichern. Dann können Sie Ihre Datenbank einfach nach Benutzern abfragen, die mit diesem Token übereinstimmen. Sie könnten auch ein Token erstellen, das mit einer eindeutigen Kennung und einem Salt-Wert generiert wird, etwa SHA(User.ID + "abcd123") , und dann nach jedem übereinstimmenden Benutzer abfragen. zB where TokenFromPost = SHA(User.ID + "abcd123") .

Eine weitere sehr gute Option ist OAuth 2 + SSL. Sie sollten ohnehin SSL verwenden, aber OAuth 2 ist auf der Serverseite ziemlich einfach zu implementieren, und Bibliotheken sind für viele gängige Programmiersprachen verfügbar.

Wenn die von Ihnen erstellte API auf einer öffentlichen Website über JavaScript zugänglich sein soll, müssen Sie auch sicherstellen, dass Sie eine Liste von URLs pro Konto für das Token validieren. Auf diese Weise kann niemand die Aufrufe Ihrer API überprüfen, das Token von Ihrem Benutzer stehlen und es für sich selbst verwenden.

Hier sind einige andere wichtige Dinge, die Sie beachten sollten:

• Whitelisting-Funktionalität. Mit APIs können Sie im Allgemeinen grundlegende Vorgänge zum Erstellen, Lesen, Aktualisieren und Löschen von Daten ausführen. Aber Sie möchten diese Operationen nicht für jede Entität zulassen, also stellen Sie sicher, dass jede eine Whitelist mit zulässigen Aktionen hat. Stellen Sie beispielsweise sicher, dass nur autorisierte Benutzer Befehle wie /user/delete/<id> ausführen können. Ebenso müssen alle nützlichen Header, die in der Anfrage des Benutzers gesendet werden, ebenfalls gegen eine Whitelist validiert werden. Wenn Sie Content-Type-Header zulassen, vergewissern Sie sich, dass alles, was der Benutzer einsendet, tatsächlich mit einer Whilelist unterstützter Inhaltstypen übereinstimmt. Wenn dies nicht der Fall ist, senden Sie eine Fehlermeldung zurück, z. B. eine 406 Not Acceptable-Antwort. Whitelisting ist wichtig, da viele APIs automatisch generiert werden oder stattdessen eine Blacklist verwenden, was bedeutet, dass Sie explizit sagen müssen, was Sie nicht wollen. Die goldene Regel der Sicherheit lautet jedoch, mit absolut nichts zu beginnen und nur ausdrücklich zuzulassen, was Sie wollen .

• Schützen Sie sich vor Cross-Site Request Forgery (CSRF). Wenn Sie Sitzungs- oder Cookie-Authentifizierung zulassen, müssen Sie sicherstellen, dass Sie sich vor CSRF-Angriffen schützen. Das Open Web Application Security Project (OWASP) bietet hilfreiche Anleitungen zum Ausschließen dieser Schwachstellen.

• Validieren Sie den Zugriff auf Ressourcen. Bei jeder Anfrage müssen Sie überprüfen, ob ein Benutzer tatsächlich Zugriff auf das spezifische Element hat, auf das er sich bezieht. Wenn Sie also einen Endpunkt haben, um die Kreditkartendetails eines Benutzers anzuzeigen (z. B. /account/card/view/152423 ), stellen Sie sicher, dass die ID „152423“ auf eine Ressource verweist, auf die der Benutzer wirklich zugreifen darf.

• Bestätigen Sie alle Eingaben. Alle Eingaben eines Benutzers müssen sicher geparst werden, vorzugsweise unter Verwendung einer bekannten Bibliothek, wenn Sie komplizierte Eingaben wie XML oder JSON verwenden. Bauen Sie nicht Ihren eigenen Parser, oder Sie stehen vor einer Welt voller Verletzungen.

Regel 5: Einfache Übernahme

Dies ist wirklich die wichtigste Regel im Bündel und baut auf allen anderen auf. Wie ich während der Dokumentationsregel erwähnt habe, probieren Sie dies mit Personen aus, die Ihre API noch nicht kennen. Stellen Sie sicher, dass sie innerhalb weniger Minuten mit mindestens einer grundlegenden Implementierung Ihrer API loslegen können, selbst wenn sie nur einem Tutorial folgen. Ich denke, 15 Minuten sind ein gutes Ziel.

Hier sind einige spezifische Empfehlungen, um die Einführung Ihrer API zu erleichtern und zu erleichtern:

• Stellen Sie sicher, dass die Leute Ihre API tatsächlich verwenden können und dass sie jedes Mal beim ersten Mal funktioniert. Lassen Sie gelegentlich neue Leute versuchen, Ihre API zu implementieren, um sicherzustellen, dass sie nicht in irgendeiner Weise verwirrend ist, gegen die Sie immun geworden sind.

• Halte es einfach. Führen Sie keine ausgefallene Authentifizierung durch. Machen Sie kein verrücktes benutzerdefiniertes URL-Schema. Erfinden Sie SOAP oder JSON oder REST oder so etwas nicht neu. Verwenden Sie alle Tools, die bereits implementiert und allgemein akzeptiert sind, sodass Entwickler nur Ihre API lernen müssen, nicht Ihre API + 10 obskure neue Technologien.

• Stellen Sie sprachspezifische Bibliotheken als Schnittstelle zu Ihrem Dienst bereit. Es gibt einige nette Tools, um automatisch eine Bibliothek für Sie zu generieren, wie Alpaca oder Apache Thrift. Derzeit unterstützt Alpaca Node, PHP, Python und Ruby. Thrift unterstützt C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi und mehr.

• Vereinfachen Sie alle erforderlichen Anmeldungen. Wenn Sie keine Open-Source-API entwickeln oder wenn es einen Anmeldeprozess jeglicher Art gibt, stellen Sie sicher, dass ein Benutzer nach der Anmeldung sehr schnell zu einem Tutorial weitergeleitet wird. Und automatisieren Sie den Anmeldeprozess vollständig, ohne dass eine menschliche Interaktion Ihrerseits erforderlich ist.

• Bieten Sie hervorragende Unterstützung. Ein großes Hindernis für die Adoption ist der Mangel an Unterstützung. Wie werden Sie mit einem Fehlerbericht umgehen und darauf reagieren? Was ist mit unklarer Dokumentation? Ein unerfahrener Benutzer? Foren, Bugtracker und E-Mail-Support sind fantastische Anfänge, aber stellen Sie sicher, dass Sie sich wirklich darum kümmern, wenn jemand einen Bug postet. Niemand möchte ein Geisterstadtforum oder eine riesige Liste von Fehlern sehen, die nicht behoben wurden.

Zusammenfassung der Web-API

Webdienste und ihre APIs gibt es in Hülle und Fülle. Leider ist die überwiegende Mehrheit schwer zu bedienen. Die Gründe reichen von schlechtem Design, fehlender Dokumentation, Volatilität, ungelösten Fehlern oder in einigen Fällen all dem oben Genannten.

Wenn Sie die Anleitung in diesem Beitrag befolgen, können Sie sicherstellen, dass Ihre Web-API sauber, gut dokumentiert und benutzerfreundlich ist. Solche APIs sind wirklich selten und werden daher mit größerer Wahrscheinlichkeit weit verbreitet und verwendet.