web-dev-qa-db-ja.com

APIを設計するためのベストプラクティスとガイドライン

APIの設計中に遵守できるガイドラインとベストプラクティスは何ですか?最低限、APIは使いやすく柔軟でなければならないことを知っています。残念なことに、これらの用語はかなり主観的なものになる可能性があるため、優れたAPI設計に関する具体的なガイドラインを探していました。

92
Vivin Paliath

以下は時計の価値があるとわかりましたJoshua Bloch- 良いAPIを設計する方法とそれが重要な理由

例はJavaですが、それでも類似点を描くことができます。特定の技術については言及しなかったため、ニッチなソリューションは必要ないと思います。

60
Gishu

大量のAPIを消費しなければならない人として...

一貫した方法でAPIを記述してください:

  1. API内で一貫した命名。まったく同じスタイルの動詞、名詞、キーワードを使用します。

  2. 使用されるターゲット環境と一致します。NETの場合は、Microsoftの命名ガイドラインを参照してください。

  3. 一貫した概念。工場パターン?ビルダーパターン?静的メソッド?インターフェース?ひとつだけ選んで、それを使い続けてください。本当に。ルールのsmall例外などはありません。それは大きな痛む親指として突き出ます。複数の例外?あなたのAPIはますますアマチュアです。

もう1つ、特異性があります。

  1. あなたがそれらを提供することを選択した場合、私が実装できる基本クラスは、実装すべき少数の明確に定義された関数を持つべきです。 「GetData()」が「object []」を返し、それを実装することを期待し、それをstring []にキャストしなければならない理由を見つけ、それが20回呼び出される理由をデバッグします。 DataPoint [] GetChartData()、string [] GetLabelData()などを使用して、実装する必要があるものを選択できるようにすることをお勧めします。

  2. PostRenderColorWheelModifyHSVBaseHandlerという名前でばかげた名前を取得しないでください。多くの場合、超固有のものをより一般的な名前+パラメーターにリファクタリングできます。

  3. 文字列パラメーターは、ノーです!列挙を使用します。のようなハンドラを使用したくない

    PostRenderHandler( "ColorWheel"、 "HSV"、someDelegate);

私は調査できる列挙型がかなり欲しいです:

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

男、私は続けることができます...そのジョシュ・ブロック男への力-よく書かれたAPIは本当に素晴らしいことができます...悪いものは本当に痛いことができます。

32

Joshua Blochからのこのトピックについて 良いプレゼンテーション があります。プレゼンテーションではJavaを使用していますが、アイデアは言語に依存しません。 別のソース(pdf) を参照してください。

12
Csaba_H

これはマイクロソフトからのリンクです: http://msdn.Microsoft.com/en-us/library/ms229042.aspx

この本もあります:フレームワーク設計ガイドライン:再利用可能な.NETライブラリの規則、イディオム、およびパターン

9
Klinger

あなたが与えている情報の量では、この量のスペースではあなたの質問には答えられないと思います。私はグーグルで「APIデザイン」と入力することからいくつかのリンクを入れました、そして最初のページでこれらをかなり良く見ます

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

http://www.artima.com/weblogs/viewpost.jsp?thread=142428

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

3
Romain Hippeau