既存のWebサイトにパブリックAPIを追加することは、ただでさえリスクを伴う冒険だが、StackExchangeのオープンな編集ポリシーはそのリスクを更に高めたようだ。Kevin Montrose氏は、最近投稿したいくつかのブログ記事で、StackExchange APIに対して行った意思決定と、そこから得られた教訓について語っている。
彼らはAPI設計を、目標と制約を決めることから始めた。例えば、主な目標の1つは、“StackExchangeの複数のサイトからデータをかき集める必要性をなくすこと”だった。StackExchangeのコンテンツは、StackExchangeのメンバーが同意しているコンテンツのライセンス契約(cc-wiki)により、第三者が再利用することが可能なのだが、以前は大量のコンテンツにアクセスするよい方法がなかったのだ。彼らの用意したAPIの最大の制約は、それが読み取り専用であることだろう。Kevin氏によれば、
書き込みはとてつもなく危険なのです。バグのある認証によるものだけでなく(以前あったJeff Atwood氏の件)、APIからの書き込みは大量の無意味なコンテンツを生み出すでしょう(想像したくもないことですが)。StackExcnahgeのサイトで実装しているガイダンス機能が知らず知らずの内に意味を失っていき、無意味な投稿が増えていくことになると思います。
我々はStackExchangeネットワークのコンテンツのクオリティを非常に高い状態に保っています(我々の標準に適合しなかったサイトを止めることもしています)。検討不足の書き込みAPIは全てを駄目にしてしまうでしょう。だから、我々はバージョン1.0ではそれを実装しなかったのです。念のため言っておくと、バージョン3.0で書き込みAPIについて再度検討する予定です。
Kevin氏はいくつかの設計のキーポイントについても述べている。
- ベクトル化リクエスト：パラメータとしてIDを受け取るほぼ全ての箇所で、一度に最大100個までIDを受け取ることができる
- レスポンスの圧縮：レスポンスはGZIPで圧縮される(例えクライアントがそれを要求していなくても)
- ソートとフィルタ：ほとんどのエンドポイントはパラメータとしてソート順、最小値、最大値、日付の範囲を受け取ることができる
しかし、もっと興味深いのは彼らが失敗した部分だ。例えば、彼らがデータの総数をデフォルトで返すようにしたことなどだ。
データ総数はページングコントロールのレンダリングや、コメントへの投票数の表示等で使われるため、それ自体は間違いではありませんでした。しかし、デフォルトで返すようにしたのは、全くもって間違いだったと思っています。
データ総数は有用ではありますが、常にそうであるとは限りません。よく実行されるのは、“ユーザーXの最も新しいN個の質問／回答を取得する”や、“ログインユーザーのトップNの質問／回答をSでソートして取得する”といったクエリです。これらの一般的なクエリではデータ総数を使いませんが、デフォルトでデータ総数を返すようになっているために、クエリを実行するたびにデータ総数を取得するコストがかかってしまいます。
別の問題は、暗黙的なデータ型の利用だ。明示的にデータ型が指定されていないため、クライアントの開発者は、フィールドからデータ型を推測しなければならないのだ。これはどんな言語でも悩ましい問題だが、このような無名のデータ型を何らかのクラスにマッピングしなければならない、静的型付言語で特に問題となる。
その他の２、３の間違いについてはここでは触れず、Kevin氏による最後の議論、無駄なリクエストクォータに移ろう。過度なAPIの利用を防ぐため、彼らはTwitter APIと同じクォータシステムを使った。
これは結局、帯域幅の観点から非常に無駄であるとわかりました。Twitterとは違い、我々のクォータはとても豊富であり(1日当り10,000リクエスト)、動的ではありません。データ総数と同じく、多くのアプリケーションはクォータについて本当に関心がありません(クォータを超えるまでは。そしてそれはレアケースです)。しかし、それらのアプリケーションはリクエストの度にクォータを取得するコストを払わなければならないのです。