Was haben großartige APIs gemeinsam? [geschlossen]

Was macht großartige APIs so großartig? Ich denke, dass das Festhalten an dem Mantra "Mach eins und mach es gut" ein gutes Zeichen ist und es wichtig ist, eine gute Zuordnung zur Problemdomäne zu haben, aber was haben großartige APIs gemeinsam?

Sie müssen vorsichtig sein, um das Hinzufügen neuer Vokabeln nur für Ihre API zu vermeiden. Meine Lieblings-APIs erklären mir Dinge in Vokabeln, die ich bereits verstehe. In diese Richtung:

Fügen Sie nicht zu viele Abstraktionen zu dem hinzu, worauf Sie aufbauen. Halte es einfach.

Ich muss schon an ein halbes Dutzend Abstraktionsebenen denken. Lass mich nicht über zusätzliche Schichten nachdenken. Gib mir nicht zu viele neue Dinge zu lernen, die meinem Endziel keinen Mehrwert verleihen. Vermeiden Sie beispielsweise die Verwendung einer eigenen speziellen Dateiklasse, die anders funktioniert als der Dateityp der Sprache, nur weil Sie der Meinung sind, dass Ihr Weg besser ist als der allgemein akzeptierte. Halten Sie sich an die allgemein akzeptierte Methode, zumindest in Ihren Schnittstellen, zum Guten oder zum Schlechten.

Bleibe bei konkreten Ideen

Versuchen Sie beispielsweise nicht, die Tatsache zu verbergen, dass der "Modell" -Teil Ihres MVC-Frameworks ein Front-End für eine Datenbank ist. Nutzen Sie das bekannte Vokabular rund um "Datenbanken". Ich weiß, was Fremdschlüssel sind. Ich weiß, was Zeilen und Spalten sind. Sprechen Sie mit mir in diesen Begriffen.

Abstrahiere nicht essentielles Wissen

Ähnlich wie bei der Arbeit mit konkreten Ideen. Verstecken Sie nicht die Tatsache, dass es sich um Dateien oder Datenbanken oder Zeilen in Datenbanken handelt. Ich kenne diese Dinge. Wenn ich es mit einem Container wie einer Liste zu tun habe, besteht eine gute Chance, dass ich die algorithmische Komplexität gängiger Operationen kennen muss. Sie können das sehr vereinfachen, indem Sie mir einfach sagen, dass es sich um eine "verknüpfte Liste" oder ein "Array" handelt. Plötzlich wird eine Vielzahl von Ideen auf Ihr Tun einwirken und es wird plötzlich Sinn ergeben. Erstellen Sie keine eigenen Ideen, die ich erst lernen muss, wenn ich bereits eine umfassende und nützliche Terminologie für das Problem habe.

Reduzieren Sie die Anzahl der Begriffe, die ich in meinem Wortschatz benötige

Wenn ich Ihre API verwende, um eine Bilddatei eines beliebigen Typs zu öffnen, sollte ich nicht viel über pngs vs gifs vs jpgs nachdenken müssen. Das machst du für mich. Es ist Ihre Kernkompetenz, nicht meine. Ich habe ein vages Verständnis, dass Sie etwas Magie haben, um dies für mich zu tun.

Eine nützliche API hat Folgendes:

• Kurze und gründliche Dokumentation. Wenn ich suche, wie eine Aufgabe implementiert werden soll, kann ich innerhalb weniger Minuten herausfinden, ob die API dazu in der Lage ist. Dies wird durch die Kürze des Textes und das Layout der Ressource erreicht. Die Dokumentation enthält Beispiele auf , wie es zu benutzen und macht auch keine Annahmen über die Leserschaft.
• Eine große, aktive Community. Ich bin begeistert, wenn ich Foren, IRC-Kanäle, Mailinglisten usw. mit aktiven Teilnehmern finde, die bereit sind, den neuen Leuten zu helfen. Ich verstehe, dass dies normalerweise bei größeren Projekten der Fall ist, aber dennoch etwas anzustreben wäre.
• Konsistenz. Wenn ich die API tatsächlich verwende , möchte ich in keiner Weise schockiert sein, wenn ich eine Methode aufrufe, oder feststellen, dass sich diese Methode Xvollständig von der im Rest der API festgelegten Konvention unterscheidet.

Gute APIs haben eine gute Dokumentation.

• Mach eine Sache und mach es großartig.
• Einfach zu bedienen, schwer zu missbrauchen.
• Einfach zu erweitern.
• Gut dokumentiert.
• Konsequenter Stil.

Diese Frage wird in "Praktisches API-Design: Geständnisse eines Java-Framework-Architekten" von Jaroslav Tulach vom NetBeans-Team behandelt.

Die einfachste nützliche Oberfläche und gute Namenskonventionen.