優れたAPIの共通点は何ですか？[閉まっている]

優れたAPIが優れている理由は何ですか？「1つのことをして、それをうまくやる」というマントラに従うことは良い兆候であり、存在することは問題領域への良いマッピングであることが重要であると思いますが、素晴らしいAPIには何が共通していますか？

APIのためだけに新しい語彙を追加しないように注意する必要があります。私のお気に入りのAPIは、私がすでに理解している語彙で物事を説明します。それらの線に沿って：

構築しているものの上にあまりにも多くの抽象化を追加しないでください。複雑にしないでおく。

私はすでに半ダースの抽象化層について考えなければなりません。余分なレイヤーについて考えさせないでください。私の最終目標に価値を加えないほど多くの新しいことを学ばないでください。たとえば、動作が異なる独自の特別なファイルクラスを使用することは避けてください。言語のファイルタイプは、一般的に受け入れられている方法よりも自分の方法が優れていると考えるだけです。少なくともインターフェイスでは、良くも悪くも、一般に受け入れられている方法を守ります。

具体的なアイデアに固執する

たとえば、MVCフレームワークの「モデル」部分がデータベースのフロントエンドであるという事実を隠そうとしないでください。「データベース」を取り巻くよく知られた語彙を活用してください。外部キーとは何かを知っています。行と列が何であるかを知っています。これらの用語で私に話してください。

不可欠な知識を抽象化しないでください

具体的なアイデアを扱うことに似ています。ファイルやデータベース、またはデータベース内の行を扱っているという事実を隠さないでください。私はこれらのことを知っています。リストのようなコンテナを扱っている場合、一般的な操作のアルゴリズムの複雑さを知る必要がある可能性が十分にあります。「リンクリスト」または「配列」を指定するだけで、これを大幅に簡素化できます。膨大な数のアイデアが突然あなたのやっていることに関係するようになり、それは突然意味をなします。問題に適用するための豊富で便利な用語集がすでにあるときに学ばなければならない独自のアイデアを作成しないでください。

ボキャブラリーで必要な用語の数を減らす

APIを使用して任意の種類の画像ファイルを開く場合、PNGとGIFとJPGについてあまり考慮する必要はありません。あなたは私のためにそれをするでしょう。コアコンピテンシーであり、私のものではありません。あなたは私のためにこれを行うための魔法を持っていることを漠然と理解しています。

便利なAPIには次のものがあります。

• 簡潔で完全なドキュメント。タスクの実装方法を検索している場合、APIにその機能があるかどうかを数分以内に見つけることができます。これは、テキストの簡潔さとリソースのレイアウトによって実現されます。ドキュメントには、その使用方法の例が記載されており、読者についての前提もありません。
• 大規模で活発なコミュニティ。フォーラム、IRCチャンネル、メーリングリストなどを見つけて新しい参加者を積極的にサポートしてくれる積極的な参加者がいることに興奮しています。これは通常、大規模なプロジェクトの場合に当てはまることを理解していますが、それでもまだ努力が必要なことです。
• 一貫性。実際にAPI を使用している場合、メソッドを呼び出すときにショックを受けたり、そのメソッドXがAPIの他の部分で設定されている規則とはまったく異なることを発見したくありません。

優れたAPIには優れたドキュメントがあります。

• 一つのことをして、それをすばらしいことをしてください。
• 使いやすく、誤用しにくい。
• 拡張が簡単です。
• よく文書化されています。
• 一貫したスタイル。

この質問は、NetBeansチームのJaroslav Tulachによる「実用的なAPIデザイン：Javaフレームワークアーキテクトの告白」で取り上げられています。

最も単純で便利なインターフェースと適切な命名規則。