Best Practices und Richtlinien zum Entwerfen einer API

Question

Welche Richtlinien und Best Practices kann ich beim Entwerfen einer API beachten? Auf das absolute Minimum, ich weiß, dass eine API einfach zu bedienen und flexibel sein sollte. Leider können diese Begriffe eher subjektiv sein, daher suchte ich nach konkreten Richtlinien für gutes API-Design.

Answer 1

Ich fand die folgenden sein eine Uhr wert Joshua Bloch - How To Design A Good API and Why it Matters

Die Beispiele sind zwar in Java, aber immer noch können Sie Parallelen ziehen. Da du eine bestimmte Technologie nicht erwähnt hast; Ich nehme an, Sie wollen keine Nischenlösungen.

Answer 2

Es gibt eine good presentation zu diesem Thema von Joshua Bloch. Die Präsentation verwendet Java, aber die Ideen sind sprachunabhängig. Another source (pdf) für einen schnellen Überblick.

Answer 3

Ich denke, Ihre Frage wird in dieser Menge an Speicherplatz mit der Menge der Informationen, die Sie geben, nicht beantwortet werden. Ich habe einige Links zusammengestellt von Eingabe von 'api Design' in Google, und auf der ersten Seite diese erhalten, die ziemlich gut aussehen

http://web.archive.org/web/20151229055009/http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf

Answer 4

Dies ist ein Link von Microsoft: http://msdn.microsoft.com/en-us/library/ms229042.aspx

Es gibt auch dieses Buch: Framework Design Guidelines: Conventions, Idiome und Muster für wiederverwendbare .NET-Bibliotheken

Answer 5

Als jemand, der Tonnen zu konsumieren hat von APIs ...

Bitte schreiben Sie Ihre API in einer konsistenten Art und Weise:

1. Konsequente Benennung innerhalb der API selbst. Verwenden Sie Verben, Substantive, Schlüsselwörter in genau dem gleichen Stil.

2. In Übereinstimmung mit der Zielumgebung wird es verwendet werden. Wenn .NET, dann konsultieren Sie Microsofts Benennungsrichtlinien.

3. Konsequente Konzepte. Fabrikmuster? Erbauermuster? Statische Methoden? Schnittstellen? Wählen Sie einfach einen aus und bleiben Sie dabei. JA WIRKLICH. Es gibt keine kleine Ausnahme von der Regel. Es wird als großer wunde Daumen hervorstehen. Mehr als 1 Ausnahme? Deine API ist mehr und mehr amateurhaft.

Hier ist noch eins: Spezifität.

1. Basisklassen, die ich implementieren kann, wenn Sie sie bereitstellen möchten, sollten wenige und klar definierte Funktionen implementieren. Sag mir nicht "GetData()" gibt ein "object []" zurück und erwartet dann, dass ich es implementiere, finde heraus, warum ich es in einen String [] umwandeln muss, und debugge dann, warum es 20 Mal aufgerufen wird. Es ist viel besser, DataPoint [] GetChartData(), string [] GetLabelData(), etc. und lassen Sie mich wählen, welche ich implementieren sollte.

2. Bitte nicht albern-lange mit Namen: PostRenderColorWheelModifyHSVBaseHandler. Sie können oft sehr spezifische Dinge in einen allgemeineren Namen + Parameter umgestalten.

3. String-Parameter sind ein No-No! Verwenden Sie Aufzählungen. Ich möchte keinen Handler wie

   PostRenderHandler verwenden ("ColorWheel", "HSV", einigeDelegate);

Ich würde viel eher wie ein Enum kann ich untersuchen:

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate); 

Man, ich könnte weitermachen ... Power zu diesem Kerl Josh Bloch - gut geschriebene APIs kann wirklich genial ... schlechte können sehr schmerzhaft sein.