Offensichtlich sind APIs in den letzten paar Jahren explodiert, aber viele von ihnen scheinen schlecht entworfen, wenn es darum geht, sie zu verwenden ... Ich habe die Möglichkeit, eine API zu entwerfen, wie ich es für richtig halte, aber ich würde es gerne haben einfach für diejenigen, die darauf zugreifen. Natürlich ist es eine große Hilfe, es so einfach wie möglich zu halten, aber was sind die Probleme, denen die Leute dort begegnet sind? Alles, was um jeden Preis vermieden oder um jeden Preis umgesetzt werden sollte?
Beantworten Sie diesen Tech Talk " So gestalten Sie eine gute API und warum es wichtig ist ". Umfasst einige wichtige Punkte und es ist sprachunabhängig.
Die Folien für die obige Präsentation sind hier verfügbar.
Einige Punkte, die wirklich bei mir Resonanz gefunden haben:
Für exzellente Beispiele für großartige APIs würde ich vorschlagen, dass Sie sich diese APIs ansehen (es ist ein Community-Wiki, also fügen Sie bitte etwas hinzu):
Um CrAPIs von guten APIs abzuheben, sehen Sie sich dieses gängige Beispiel an, in dem Sie alle Zeilen aus einer Datei lesen und ausdrucken. (Java):
%Vor%Ich habe File IO mit Java bei so vielen Gelegenheiten gemacht, und ich muss immer noch nachsehen, wie File IO jedes Mal ausgeführt wird, und das ist eine knappe Art, Dinge wirklich zu tun.
vs (Ruby)
%Vor%Ein weiteres Beispiel aus Javascript. Das Einfügen und Entfernen von Elementen aus einer bestimmten Position in einem Array ist etwas, von dem Sie annehmen, dass es sich um eine allgemeine Aufgabe handelt.
So können Sie es tun:
%Vor%Jetzt ist es toll, dass die Designer eine großartige Arbeit bei der Wiederverwendbarkeit von Code geleistet haben, aber ich kann nicht jedes Mal, wenn ich dies tun muss, w3schools.com öffnen. Daher werden diese einfachen Wrapper in allen meinen Projekten als Kernerweiterungen von Array hinzugefügt:
%Vor%Hinweis: Es geht nicht um einen kürzeren Code, sondern um Code, der unter anderem einfacher, leichter zu merken, lesbar und konsistent ist.
Siehe auch diese verwandte Frage - Wie definierst du a gute oder schlechte API?
Um eine großartige API zu erstellen, ist es meines Erachtens wichtig, sie neben einer oder mehreren realen Anwendungen zu entwickeln. Auf diese Weise können Sie testen, wie vollständig und elegant Ihre API häufig auftretende Probleme beseitigt.
Ich empfehle Ihnen, Framework Design Guidelines zu lesen.
alt text http://davesbox.com/images/books/FrameworkDesignGuidelines2ndEditionLarge.jpg
Schreiben Sie zuerst den Client-Code. Bitten Sie Ihre Kollegen, den Client-Code zu schreiben, der Ihre API verwenden und Ihr Design aus dem Client-Code weiterentwickeln soll.
Wenn Sie eine Math API schreiben, dann bitten Sie Ihre Kollegen, Client-Code zu schreiben, als ob sie ihn benutzen würden. Dies wird Ihnen einige gute Ideen geben, um damit zu beginnen.
Obwohl diese Frage sehr subjektiv ist, ist es wichtig zu wissen, was Sie mit Ihrer API leichter erreichen können (schreiben Sie eine kleine Menge Code auf einfache Weise) und machen Sie schwer die Dinge zu machen, die sie waren ursprünglich nicht vorgesehen.
Um Ihnen ein sehr einfaches Beispiel zu geben, nehmen wir an, Sie schreiben eine API in C # und Sie haben eine Methode, die eine Sammlung von Elementen zurückgibt. Welchen Typ sollten Sie zurückgeben? In diesem Fall könnten Sie die folgende Frage stellen, um Ihnen bei der Entscheidung zu helfen: Ich möchte, dass der Verbraucher meiner API die Sammlung ändert (Elemente hinzufügt oder entfernt). Wenn Ihre Antwort nicht lautet, sollten Sie eine ReadOnlyCollection von Elementen zurückgeben, andernfalls sollten Sie eine Liste der Elemente zurückgeben.
Fordern Sie diese Fragen auf, damit Sie Ihre API besser gestalten können. Denken Sie immer an die Ziele, die Sie ursprünglich für Ihre API festgelegt hatten. Der Versuch, zu weit zu kommen, ist ein sehr häufiger Grund dafür, dass viele APIs zu einem Frankstein werden.
Wie ein anderer Benutzer in seiner Antwort sagte, eine API zusammen mit einem realen System zu entwickeln, ist immer der beste Ansatz.
Vielleicht können Sie damit beginnen, Gründe dafür aufzuzählen, warum Sie "sagen, aber viele von ihnen scheinen schlecht entworfen zu sein, wenn es darum geht, sie zu verwenden" .
Erweitere Anurags Beitrag, hier ist eine Liste mit einigen Notizen, die beim Entwerfen / Implementieren einer API beachtet werden sollten
Es ist inspiriert von einer großartigen Präsentation von Joshua Bloch. Normalerweise halte ich es während der Anfangsphase des API-Designs griffbereit. Das Dokument ist in einer Art Checkliste gestaltet, beachten Sie unbedingt "Wie wird dieses Dokument verwendet?" oben gegeben.
Tags und Links api