API設計とAPI記述はマシン間の単なるインターフェイス規約以上のものだ。Apiaryの共同創業者でCEOのJakub Nesetril氏は、API記述の真の消費者は、課された取り決め、ユーザビリティ、コミュニケーションに関心を持っている開発者である、と指摘する。API設計と新たなAPIツールおよびワークフローに対するApiaryのアプローチについて、Jakub氏から話を聞いた。
InfoQ: 最近、API StrategyカンファレンスのBest Practices in API Designというパネルでプレゼンされましたね。そこであなたは「APIを構築するたった1つのやり方」というのは存在しないと述べました。その哲学について、またApiaryがやっていることにその哲学がどう関係するのかについて、少し教えてもらえませんか？
JN: 歴史的に、APIというのは2つのコンピュータプログラム間のインターフェイスとして見なされてきました。ところが現実には、APIというのは開発者間、リアルな人と人とのインターフェイスなのです。もし開発者があなたのAPIの使い方を知らなければゲームオーバー、あなたのプロジェクトは失敗するでしょう。
API（そして一般的なソフトウェアのインターフェイス設計）はUI設計と非常によく似ています。流行による影響を受け、文化的背景によっても違います（プログラミングにおいては、言語やフレームワークをとりまく文化を意味します）。非常に口を出しやすいのですが、正しい設計とな何か、人それぞれ異なる意見を持っています。
「たった1つの」UI設計を求めることがばかげているように、規範となる1つのAPI設計というのは存在しません。それでも、主観をやわらげるためのテクニックなら存在します。この10年、ユーザインターフェイスの進化において、ユーザ中心設計とユーザ体験へのフォーカスが設計の中心として登場するのを私たちは目にしました。アジャイル、ラピッドイテレーション、顧客やステークホルダーとの密接なフィードバックループを中心として、同様のアプローチをAPI開発に持ち込む必要があります。
InfoQ: あなた方のAPI Blueprintを含め、たくさんのAPI記述標準が導入を競っていますね。その中には、JSONやMarkdown、YAML、XMLをベースにしているものもあります。どのアプローチがベストだと考えていますか？ あなたはどうしてMarkdownを選んだのですか？
JN: Apiaryを始めた当時、XML、JSON、YAMLといったフォーマットが存在しました。私たちは新しいものを再発明しないよう努めました。ところが、これらの言語はあまりに複雑すぎると思いました。テクニカルドキュメントライターやAPIの消費者など、他の役割を分かち合っているなら、なおさらです。また、彼らはすぐれたAPIドキュメント、大量のヒューマンリーダブルなテキストを伝えるのが本当に苦手なのです。
私たちは開発者の間で人気があって、構造化されたデータを記述するのに使えて、文の段落分けもできるフォーマットを探しました。目標は、人間にとって非常に読みやすく、書きやすいものを見つけることでした。そして、技術屋にもそうでない人にも、同じように理解できるものを求めました。Markdownはここ数年で、事実上あらゆるオープンソースプロジェクトで使われるようになり、GitHub PagesとJekyllパブリッシングシステムのコアになっています。開発者はこれらをずっと使っています。
InfoQ: 規約ベースのAPI開発に代わり、ハイパーメディアを支持している開発者もいます。はっきりした答えがあるのかわかりませんが、API規約 vs. そうでないものについて、どう考えていますか？
JN: ハイパーメディアには大きなポテンシャルがあると思いますが、今のところ限定的ですね。ハイパーメディアは導入に苦しんでいます。もし広く導入されれば、APIの消費側は劇的に移行するでしょう。それでも、検証や自動テスト、ツールといったところには、規約の便利さが残ると思います。すぐれたツールのサポートがない限り、状況はおそらく変わらないでしょうね。でも、かしこい人たちがツールの改善に取り組んでいるので、将来はこちらの方に行くんじゃないでしょうか。
InfoQ:あなたは最近、Blueprintに対するAPI実装の自動テストのために、Dreddというツールを立ち上げましたね。API設計およびAPI開発に関して、あなたは具体的なワークフローの実現に向けて取り組んでいるように見えます。それについて説明してもらえますか？
JN: この10年で、ソフトウェア開発は従来の静的なウォーターフォール設計よりもアジャイルなイテレーションを好むようになりました。アジャイルでは、自動テスト、コードカバレッジ、継続的インテグレーションといったものが登場しました。ところがAPIとインターフェイス規約に関して、私たちはまだ1999年のようなパーティ状態です。前払いの設計、巨大な開発プロジェクト、古くなったドキュメント、コードカバレッジの欠如、継続インテグレーションの欠如。Apiaryでは、それを変えようと取り組んでいます。
Dreddはその好例です。開発者ならみな、たいくつで手作業の間違いやすいタスクは自動化すべきだとわかています。APIドキュメントが最新であることを確かめるのは、まさにその1つです。だれもがドキュメントのメンテを嫌っています。Dreddにより、私たちはコードカバレッジをAPIドキュメントに持ち込みます、世の中の継続的インテグレーションプロバイダと基本的に互換性があるやり方で。
InfoQ: 開発者エンゲージメントがAPIの導入と成功のための「秘伝のタレ」のようですね。開発者エンゲージメントの観点で、みんなが見失っている重要なものは何でしょうか？
JN: ユーザビリティと権限付与にフォーカスすることです。まだあまりできていないと思います。成功しているAPIプロジェクト（そして一般的に開発者にフォーカスした会社）を調べてみると、みな強いブランドを持ち、プロダクトにすばらしいユーザ体験があり、これまでできると思っていなかったようなことができる権限をユーザに付与しています。これはそう難しいことではありませんが、あらためて作るのはとても大変です。ユーザニーズへの共感というのは、トレーニングしたり獲得したりするのが容易ではありません。Apiary設計の大部分が、API設計者、API開発者、API消費者をまとめてコラボレーションしやすい環境を作ることにフォーカスしているのは、そのためです。
InfoQ: Apiaryを使って開発中のAPIが25,000もあるということですが、APIマーケットやAPIリポジトリといった形で、それを活用する計画はありますか？
JN: 毎週増えているので、その数を追いかけるのは大変です。今は35,000で増えています。ほんの1年前まで、業界のアナリストたちは世界中合わせて50,000あるいは80,000 APIあるかどうかだと真面目に話していました。今では実際の数はもっともっと大きいことがわかっています。この12か月のApiaryの急激な成長にもかかわらず、業界の大多数は内製の独自ツールを使っています。成長の余地はまだまだあります。
私たちは独力で最善をつくすこと、開発者に権限を付与するツールを構築することにフォーカスしています。APIマーケットやAPIリポジトリといったアイデアは一見すると魅力的に思えるのですが、まだ本当に価値をもたらすものを目にしたことがありません。
Apiary Inc.はサンフランシスコを本拠地とし、チェコのプラハに開発拠点を持っている。この会社はJakub Nesetril氏とJan Moravec氏が創業し、2012年末に革新的なAPI設計プラットフォームのベータ版を公開した。Apiaryはこれまでに35,000以上のAPIを集め、世界最大のAPIコレクションに成長している。なかでもアーリーカスタマーはAkamaiやGoodDataの開発者ポータルだ。私たちは、API設計、記述、ツール、テストについてJakub Nesetril氏に話を聞いた。