「APIデザインの極意」 の 第3章 優れたAPIを決定づけるもの で気になった部分の抜粋
APIデザインの極意 Java/NetBeansアーキテクト探究ノート
- 作者: Jaroslav Tulach
- 出版社/メーカー: インプレス
- 発売日: 2014/07/02
- メディア: Kindle版
- この商品を含むブログ (9件) を見る
メソッドとフィールドのシグニチャ
- システムのコンポーネント間でのコミュニケーションにリフレクションが必要なのであれば、何かが間違っているか、既存のAPIでは不十分であることを示している
APIとしてのテキストメッセージ
- テキストメッセージを解析するしかない状況に気を付ける
- 他の方法で情報が利用できなければ、人々はコードが生成したテキスト出力を解析してしまう
プロトコル
- ネットワークを介して送信されるメッセージの形式を意味するプロトコルもAPIの一つである
- このAPIの利点は、「あなたの」サーバで起きているすべてのアクセス頻度と通信を計測して分析できること
- ネットワークプロトコルの問題点は、アプリケーションとの会話に使用される様々なクライアントやプロトコルバージョンが拡散していくこと
- プロトコルのようなAPIが後方互換性を保ちながら発展する必要がある理由は、個々の参加者の独立したライフサイクルによって問題が拡大するからである
- お互いに通信しあう２つのプログラムは異なるバージョンであり、少し異なったバージョンのプロトコルを必要とするのはほぼ確実である。それでもプログラムは通信する必要がある
振る舞い
- APIが提供している抽象的概念がどれだけ優れているかに関係なく、 その背後にある実装はたいていは漏れ出しており、その結果APIの一部にもなっている
- コンポーネントの振る舞いが変わらない場合にだけ、そのユーザは最終アプリケーションでそのコンポーネントを何も考えることなく新たなバージョンに置き換えることができる
APIの広い定義
- APIの定義は、クラスやメソッドあるいは関数とシグニチャの単純な集まりをはるかに超えている
- 大きなシステムコンポーネント無知な状態で組み立てるのに役立つという意味でのAPIは単純なテキストメッセージから複雑で把握するのが難しいコンポーネントの振る舞いなどと範囲が広い
APIの品質検査方法
- APIの美しさだけが、優れたAPIの唯一の測定方法になることはありません
- 使いやすく、広く受け入れられ、生産的なAPIを設計するという目的からそれるべきではない
- 私たちは、個々のAPIが特定の目的を満足させているかを測定する方法を作りだす必要がある
■理解しやすさ
- APIの作成に最も似た活動は本を書くことです
- 一人の著者と多数の読者がいる。読者は著者について何かしら知っているが、著者は読者についてはほとんど知らない
- 読者のスキルと知識を正しく推測することは、理解しやすいAPIにするために細心の注意が必要な芸術的な部分となる
- ほとんどのAPIのユーザは、 自分が行いたいことと似たようなことを行っている既存アプリケーションを探し、そのアプリケーションをコピーして必要に応じて修正する という方法をとる
- APIの使用方法の多くの例を示すことで開発者が必要とすることに近い例を見つける可能性が高まる
- 開発者がAPIを理解する可能性を大幅に高める
- APIが使用している概念が新しければ新しいほど豊富な例が役立つ
■一貫性
- APIのユーザがある概念を理解するのに時間を費やさなければならないのであれば、その概念をAPI全体に対し一貫して適用できることが重要
■発見できること
- どんなに美しいAPIであっても、 想定している利用者がそのAPIを発見できなかったり、使用方法を容易に理解できなければ役に立たない
- APIのユーザはクラスの集まりには興味はない
- ユーザは自分の仕事を終わらせることに興味があり、そのためにはAPI利用例を見て行いたいことに近い方法を選択できるようにすることが重要である
- 提供するAPIの種類に関係なく開始地点としての役割を果たし、人々の問題を解決するために正しい方向に向かわせる単一の場所を提供することは重要
- 人々はクラスという観点から考えたりはしないので、その開始地点を実際の目的や仕事あるいは少なくとも期待される目標や仕事に基づくように最適な方法で構成することが重要である
■単純な仕事は簡単でなければならない
- APIの基本的な誤りは、１つのAPIに異なるグループが興味を持つ複数の項目を入れてしまうことである
- APIの1つの側面にしか興味が無い人々には、全く異なるグループに向けて設計された部分によって注意がそらされてしまい、興味のある部分を発見できなくなってしまう
- 取るべき手段は、 APIを２つ以上の別の部分に分けてしまうこと
- 呼び出し側向けとAPIに機能を追加するプロバイダ向けでパッケージ（名前空間）を分けてしまう等
- たとえばJavaMail APIは膨大な数の概念とクラスが混在しているので、メールの送受信をするだけでもかなりの分量のコードを書く必要がある。
- このAPIは、プロバイダ向けに最適化されてしまっており、この誤った最適化によりJavaのメールアプリケーションを比較的少なくしてしまっている原因になっている
■投資の保全
- APIのユーザがそのAPIで本当に満足するためには、新しいバージョンのライブラリのリリース時に、それまで作成したものが動かなくなることが無いことを信用できなければならない
- ライブラリに対してコーディングすることは時間・学習・労力・お金の投資である
- API設計者のもっとも重要な責任は、そのライブラリを使用する人々の投資が無駄にならないようにすること
- ユーザがAPIで良い経験を積めば積むほどAPIの良さを周りに話し、そのAPIを使用することに良い印象を持ち、そのAPIの利用は促進されて広く知られるようになる
- 結果としてAPIに好意を持って利用している人たちのコミュニティが形成される
- そのため、参加者の投資を無駄にしないことが重要であり、API契約を互換性のある方法、あるいは、少なくとも予測可能な方法で発展させることに努めることが常に重要