Web API（Application Programming Interface）は、現代の「つながる世界」の大黒柱とも言えるものである。ソフトウェアは、これらのインターフェイスを使ってやり取りする。スマートフォンにインストールされたアプリケーションからバックエンドサーバーの裏側まで、APIはそれこそどこにでも存在する。単なる技術的なインターフェイスと見なされていようと、それ自体が製品と見なされていようと、すべてのシステムが、その規模や目的を問わず、APIに依存している。ハイテクスタートアップや巨大なインターネット企業から、非技術系の中小企業、大企業、政府機関まで、すべての企業や組織に同じことが当てはまる。
このつながる世界の大黒柱がAPIであるとすれば、APIの設計はその土台である。APIベースのシステムを構築して進化させるにあたって、APIの設計は常に最大の関心事でなければならない。そのシステムが誰にでも公開されるのか、奥深くに隠されるのか、APIを1つだけ作るのか複数作るのかは関係ない。そうしたシステムの成否は、それらすべてのAPIの設計の品質に直接左右される。
しかし、APIを設計するとは、実際にどういうことなのだろうか。そして、APIを設計するために何を学ぶ必要があるのだろうか。これらの質問に答えるには、APIとは何か、そして誰のためにAPIを設計するのかについて考える必要がある。そして、APIの設計が単なるアプリケーションのプログラミングインターフェイスの設計ではないことも理解しておく必要がある。
1.1 APIとは何か
スマートフォンを所有する人の数は数十億人に達しており、スマートフォンを使ってソーシャルネットワーク上で写真が共有されている。APIがなければ、このようなことは不可能だっただろう。ソーシャルネットワークモバイルアプリケーションを使った写真の共有では、さまざまな種類のAPIが使われる（図1-1）。
まず、ソーシャルネットワークモバイルアプリケーションが写真を撮るためにAPIを使ってスマートフォンのカメラを操作する。次に、アプリケーションに埋め込まれた画像ライブラリをそのAPIから操作することで、写真の色を反転させることができる。そして最後に、ネットワーク（通常はインターネット）経由でアクセスできるリモートAPIを使って、ソーシャルネットワークサーバーでホストされているサーバーアプリケーションに加工した写真を送信し、共有する。したがって、このシナリオでは、ハードウェアAPI、ライブラリ、リモートAPIの3種類のAPIが必要となる。本書で説明するのは、このうちのリモートAPIである。
APIは、その種類を問わず、ソフトウェアの作成を単純化する。しかし、リモートAPI―――特にWeb APIにより、ソフトウェアを作る方法に大変革が起きている。最近では、リモートソフトウェアを組み合わせることで、何でも簡単に作ることができる。しかし、そうしたAPIがもたらす無限の可能性について話をする前に、本書においてAPIという言葉が実際に何を意味するのかを明確にしておくことにしよう。
1.1.1 APIはソフトウェアのWebインターフェイス
本書では、APIとはリモートAPIのことである。もう少し厳密に言うと、Web APIのことである。つまり、ソフトウェアのWebインターフェイスである。APIは、どのような種類のものであれ、何よりもまずインターフェイスであり、2つのシステム、対象者、組織などが出会い、やり取りするポイントである。APIという概念は、最初は理解しにくいかもしれない。しかし、図1-2を見ながらアプリケーションのユーザーインターフェイス（UI）と比較すれば、どのようなものであるかが少し見えてくる。
モバイルアプリケーションのユーザーは、アプリケーションを操作するために、そのUIが表示されているスマートフォンの画面をタッチする。モバイルアプリケーションのUIは、ボタン、テキストフィールド、ラベルといった要素を画面上に表示できる。ユーザーはそれらの要素を使ってアプリケーションとやり取りし、情報を表示または提供したり、メッセージや写真の共有などのアクションを開始したりできる。
私たち人間がアプリケーションのUIを使ってアプリケーションを操作するのと同じように、アプリケーションも別のアプリケーションのプログラミングインターフェイスを使ってそのアプリケーションを操作できる。UIが入力フィールド、ラベル、ボタンなどを提供するのに対し、APIは関数を提供する。画面上に表示された要素がそれらの使い方に応じて異なるフィードバックを返すのに対し、関数は入力データを要求したり、フィードバックとして出力データを返したりする。他のアプリケーションは、それらの関数を使ってそのアプリケーションとやり取りすることで、情報を取得または送信したり、アクションを開始したりできる。
厳密に言うと、APIは何らかのソフトウェアによって公開されるインターフェイスにすぎない。つまり、内部の実装（そのAPIが使われたときにソフトウェアの内部で実際に呼び出されるコード）を抽象化したものにすぎない。しかし、APIという用語は、APIとその実装を含め、ソフトウェア製品全体を指すものとして使われることが多い。その意味では、APIはソフトウェアのインターフェイスだが、本書で言うAPIは単なるAPIではなく、Web APIのことである（図1-3）。
スマートフォン上で稼働しているモバイルアプリケーションは、リモートサーバー上でホストされているサーバーアプリケーションが公開しているAPIを利用（消費）する。サーバーアプリケーションはよくバックエンドアプリケーションと呼ばれ、単にバックエンドと呼ばれることもある。このため、モバイルアプリケーションはコンシューマ、バックエンドはプロバイダと呼ばれる。これらの用語は、アプリケーションを作る（APIを消費または提供する）企業や人々にも当てはまる。この場合は、モバイルアプリケーションの開発者がコンシューマ、バックエンドの開発者がプロバイダとなる。
通常、モバイルアプリケーションはバックエンドと通信するために誰もが知っているインターネットというネットワークを利用する。ここで注目すべき点は、インターネットそのものではなく（このような通信はローカルネットワーク経由でも可能である）、これら2つのアプリケーションがネットワーク経由で通信する方法である。モバイルアプリケーションが写真やメッセージをバックエンドアプリケーションに送信するときには、HTTP（Hypertext Transfer Protocol）を利用する。コンピュータやスマートフォンでWebブラウザを開いたことがあれば、あなたもHTTPを（間接的に）使っている。
HTTPはすべてのWebサイトで使われているプロトコルである。http://apihandyman.io（または、そのセキュアバージョンであるhttps://apihandyman.io）のようなアドレスをアドレスバーに入力して［Enter］キーを押すか、Webブラウザのリンクをクリックすると、そのWebサイトのコンテンツを表示するためにWebブラウザがHTTPを使ってそのWebサイトをホストしているリモートサーバーと通信する。リモートAPI──少なくとも本書で説明しているAPIは、Webサイトと同じようにHTTPに依存している。Web APIと呼ばれるのはそのためだ。
したがって、本書では、APIとはWeb APIのことである。Web APIはソフトウェアのWebインターフェイスである。しかし、そうしたAPIがなぜそれほど重要なのだろうか。
1.1.2 APIはソフトウェアをLEGOブロックに変える
これまで何千、あるいは何百万というモバイルアプリケーションとそれらのバックエンドが作られてきたのはWeb APIのおかげだが、話はそれで終わりではない。それどころか、Web APIはソフトウェアを再利用可能なブロックに変え、簡単に組み立てられるようにすることで、創造性を解き放ち、イノベーションをもたらしている。先ほどの例に戻って、ソーシャルネットワーク上で写真を共有するときに何が起きるのか見てみよう。
ソーシャルネットワークのバックエンドは、写真とメッセージを受け取ると、写真をサーバーのファイルシステムに格納し、写真のIDとメッセージを（あとから実際のファイルを取り出せるように）データベースに格納する。写真を格納する前に、その写真に友達が写っているかどうかを検出するために、独自に開発した顔認識アルゴリズムを使って写真を処理することもある。1つのアプリケーションが別の独立したアプリケーションのためにすべての処理を行うというのは、1つの可能性である。別の例を見てみよう（図1-4）。
バックエンドAPIは、ソーシャルネットワークモバイルアプリケーションとWebサイトの両方で使われることがあり、その実装はまったく異なることがある。バックエンドは共有する写真とメッセージを受け取ると、どちらのアプリケーションから送信されたとしても、サービスプロバイダのAPIを使って写真の格納を委託できる。また、独自に開発したタイムラインソフトウェアモジュールのAPIを使って写真のIDとメッセージを格納することもできる。顔認識はどのように処理できるだろうか。顔認識サービスを提供している企業に、もちろんAPIを使って委託することが考えられる。
図1-4では、どのAPIも機能を1つだけ提供している。これは図をできるだけ単純にするためであり、1つのAPIが多くの機能を提供してもおかしくない。たとえば、友達の追加、友達の一覧表示、あるいはタイムラインの取得といった機能をバックエンドが提供することも考えられる。
これはソフトウェア版のLEGOブロックのように見える。あなたも知っているように、ブラスチックのブロックを組み合わせて何か新しいものを作るあれである（「全体が各部分の総和よりも大きい」ことに気付いたとき、アリストテレスも使っていたに違いない）。想像力を働かせれば、可能性は無限にある。
子供の頃、筆者はLEGOブロックで何時間も遊んだものである。ビルや車や飛行機や宇宙船など、作りたいと思ったら何でも作っていた。作るのに飽きたら、全部ばらして新しいものを作り始めることもできたし、パーツをいくつか取り換えて作り変えることもできた。すでに作っていたものを合体させて、たとえば巨大な宇宙船を作ることもできた。APIの世界も同じであり、ソフトウェアブロックでできた巨大なシステムを分解できる。そうしたシステムを組み立てたり、置き換えたりできるのも、APIのおかげである。ただし、小さな相違点がいくつかある。
どのソフトウェアブロックも、他の多くのアプリケーションで同時に使うことができる。先の例で言うと、バックエンドAPIをモバイルアプリケーションとWebサイトから同時に使うことができる。通常、APIは（1つではなく）多数のコンシューマによって利用されることを前提に開発されている。そのようにしておけば、そのつど何もかも作り直さずに済むからだ。各ソフトウェアブロックは、ネットワークに接続していてAPIから利用できる状態であれば、どこでも単体で稼働できる。
このことは、パフォーマンスとスケーラビリティを管理するのに都合がよい。というのも、図1-4の［顔認識］のようなソフトウェアブロックは、［ソーシャルネットワークタイムライン］ソフトウェアブロックよりもはるかに多くの処理リソースを必要とするからだ。［顔認識］ブロックがソーシャルネットワーク会社によって実行されている場合、このソフトウェアブロックがより高性能な別の専用サーバーにインストールされ、［ソーシャルネットワークタイムライン］ブロックがより小型のサーバーで稼働することは十分に考えられる。そして、単純なネットワーク接続を通じてアクセスできるということは、誰かが提供しているAPIを誰でも利用できるということだ。
APIの世界では、パブリックAPIとプライベートAPIという2種類のAPIを提供している2種類のブロックがある。［顔認識］ブロックと［フォトストレージ］ブロックを構築して実行するのは、ソーシャルネットワーク会社ではなくサードパーティである。サードパーティが提供するAPIはパブリックAPIである。
パブリックAPIは、サービスまたは製品として他の企業が提案するものである。あなたはそれらのAPIを構築したり、インストールしたり、実行したりせず、それらのAPIを利用するだけである。パブリックAPIは、そのAPIを必要としていて、サードパーティプロバイダの使用条件に同意するすべての人に提供される。他のソフトウェア製品と同様に、パブリックAPIが無償で提供されるか、有償で提供されるかは、APIプロバイダのビジネスモデルによる。パブリックAPIは創造性を解き放ち、イノベーションをもたらす。
また、あなたが思い描いているものを作る時間を大幅に短縮することもある。スティーブ・ジョブスの言葉を借りるなら、そのためのAPIがある。自分ではとうてい作れないものがすでにあるとしたら、それを利用しない手はない。先の例では、ソーシャルネットワーク会社は自身の専門分野（人々をつなぐこと）に専念し、顔認識はサードパーティに委託している。
とはいえ、パブリックAPIはAPIという氷山の一角にすぎない。［ソーシャルネットワークバックエンド］ブロックと［ソーシャルネットワークタイムライン］ブロックは、ソーシャルネットワーク会社が社内用に作ったものである。タイムラインAPIを利用するのは、ソーシャルネットワーク会社が作ったアプリケーション（図1-4のソーシャルネットワークバックエンド）だけである。モバイルバックエンドについても同じで、それを利用するのはソーシャルネットワークモバイルアプリケーションである。これらのAPIはプライベートAPIである。
そして、プライベートAPIは無数に存在する。プライベートAPIはあなたが自分のために構築するものである。そのAPIを利用するのは、あなた、またはあなたのチーム、部署、会社で働いている人々が作るアプリケーショだけである。この場合、あなたはAPIプロバイダであり、APIコンシューマでもある。
純粋なプライベートAPIとパブリックAPIの間には、さまざまな相互作用がある。たとえば、オンプレミスサーバーにCMS（Content Management System）やCRM（Customer Relationship Management System）のような市販のソフトウェア製品をインストールするとしよう。そして、これらのアプリケーションはAPIを提供することがある（より厳密には、APIを提供しなければならない）。
これらのAPIはプライベートAPIだが、これらのAPIを構築するのはあなたではない。それでも、（特に）あなたのブロックに他のブロックをつなぐために、あなたが意図したとおりに使うことができる。もう1つの例として、APIの一部を顧客や一部の提携企業に公開することが考えられる。そのようなほぼパブリックなAPIは、よくパートナーAPIと呼ばれる。
しかし、どのような状況でも、APIは基本的にソフトウェアを再利用可能なソフトウェアブロックに変える。そして、あなたや他の人がそれらのブロックを組み合わせることで、それこそ何でもできるモジュールシステムを作り上げることができる。だからこそAPIはこんなにおもしろいわけである。しかし、なぜAPIの設計を重視すべきなのだろうか。
1.2 APIの設計はなぜ重要か
APIは便利だが、ソフトウェアの技術的なインターフェイスにすぎないように思える。では、そのようなインターフェイスの設計がなぜ重要とされるのだろうか。APIはソフトウェアによって利用される、というのはそのとおりである。しかし、APIを利用するソフトウェアを作るのは誰だろうか。開発者、つまり人である。
このような人々は、これらのプログラミングインターフェイスが他の（うまく設計された）インターフェイスと同じくらい便利でシンプルなものであることを期待する。うまく設計されていないWebサイトやモバイルアプリケーションのUIを見たとき、あなたはどのような反応を示すだろうか。リモコンやドアのような日常的なものがうまく設計されていなかったら、あなたはどう感じるだろうか。
イライラするかもしれないし、怒ったり怒鳴ったりするかもしれないが、おそらく二度と使うもんかと思うだろう。そして場合によっては、うまく設計されていないインターフェイスは危険ですらある。だからこそ、どのようなインターフェイスの設計も重要なのである。そして、APIも例外ではない。
1.2.1 パブリックAPIとプライベートAPIは他の開発者のためのインターフェイス
1.1.1項で説明したように、APIのコンシューマは、APIを利用するソフトウェアの場合と、そのソフトウェアを開発している企業または個人の場合がある。コンシューマはすべて重要だが、最初に考慮すべきコンシューマは開発者である。
ソーシャルネットワークの例は、さまざまなAPIで構成されていた。まず、データストレージを扱い、プライベートAPI を提供するタイムラインモジュールがある。そして、（他の企業から提供される）パブリックAPIとして顔認識API とフォトストレージAPI がある。これら3つのAPIを呼び出すバックエンドはどこからともなく発生するわけではなく、ソーシャルネットワーク会社が開発する。
たとえば、顔認識APIを利用する開発者は、顔認識を行う写真を送信し、その結果を処理するためのコードをソーシャルネットワークソフトウェアに記述する。要するに、ソフトウェアライブラリを利用するときと同じである。このような開発者は、顔認識APIを作った開発者ではない。彼らは別々の企業で働いており、おそらく知り合いではない。
また、モバイルアプリケーション、Webサイト、バックエンド、データストレージモジュールについても、同じ会社の異なるチームによって開発されることが考えられる。それらのチームどうしが知り合いかどうかは会社の組織構造によるだろう。そして、社内の開発者なら社内で開発されたすべてのAPI のことをよく知っていて当然かもしれないが、いつかは新しい開発者がやってくる。
このため、APIがパブリックとプライベートのどちらであっても、どのような理由で作られたのであっても、会社の組織構造がどのようなものであっても、いつかは他の開発者によって使われることになる。つまり、そのAPIを公開しているソフトウェアの作成に関わっていない人が使うことになる。
だからこそ、初めての人でもコードを問題なく記述できるようなAPIにするために、あらゆる手を尽くさなければならない。開発者は、それらのAPIが他のインターフェイスと同じように便利でシンプルなものであることを期待する。だからこそ、APIの設計は重要なのである。
