ウェブAPIの紹介

まずはAPIを高い視点から見ていきます — これは何なのか、どう働くのか、あなたのコードでどう使うのか、どういう風に作られているのか? また様々なクラスのAPIは何なのか、どのような使い方があるのかも見ていきます。

APIって何?

Application Programming Interfaces (APIs)は、開発者が複雑な機能をより簡単に作成できるよう、プログラミング言語から提供される構造です。複雑なコードを抽象化し、それにかわる簡潔な構文を提供します。

実世界の例として、あなたの家、アパートや他の住処にある電気のコンセントについて考えて下さい。あなたの家で機器を使いたい時には、電源コードのプラグをコンセントに差し込めば事足ります。電源に直接結線したりしないでしょう — そんなのは非効率ですし、あなたが電気工事士でなければ、やってみるには難しいし危険です。

画像提供: 超タコ足コンセント by The Clear Communication People, Flickr より

それと同じことで、そうですね、例えば3次元グラフィックのプログラムをJavaScriptやPythonのような高レベル言語で書かれたAPIを使ってやる方が、CやC++のような低レベル言語から直接コンピュータのGPUやグラフィック機能を叩いてやるよりも、ずっと簡単です。

クライアント側 JavaScript でのAPI

クライアント側APIでは、実際非常にたくさんのAPIが使えます — それらはJavaScript言語本体の一部ではなく、あなたにスーパーパワーを与えるべくJavaScript言語のコアの上に築かれた代物です。それらはおおよそ二つのカテゴリに分けられます:

• ブラウザーAPIはウェブブラウザに組込まれていて、ブラウザやコンピュータの環境の情報を取得し、これを使って役に立つややこしい事を行えるようにするものです。 例えばGeolocation API は位置情報を取得するための簡単なJavaScript構造を提供するので、例えばグーグルマップにあなたの居場所を表示するような事ができます。裏で実際にはブラウザは低レベル(例えばC++)の複雑なコードをいくつか使ってデバイスのGPS機器(あるいは位置情報を得られる他のなんだか)と通信し、位置情報を取得し、あなたのコードから利用できるようにブラウザー環境に情報を戻しています。ですがここでもこの複雑な事柄はAPIで抽象化され隠蔽されます。
• サードパーティAPIはデフォルトではブラウザに組込まれておらず、普通はコードと情報をウェブのどこから読み込まねばなりません。例えば Twitter API を使えばあなたのウェブサイトにあなたの最新のツイートを表示するような事が可能になります。TwitterAPIは、Twitterサービスに特定の情報を要求したりするのにあなたが使える特別な構造のかたまり、を提供します。

JavaScriptとAPIとその他JavaScriptツールの関係

ここまででクライアント側APIとは何か、JavaScript言語とどう関係しているのかお話しました。もっとはっきりさせるために一度おさらいして、ついでに他のJavaScriptツールがどう関係してくるのかもお話しましょう:

• JavaScript — ブラウザに組込まれた高レベル言語で、ウェブページやアプリに機能を実装するのに使えます。Nodeのようなブラウザ以外の他のプログラミング環境でも使えるのは覚えておいて下さい。
• ブラウザーAPI — ブラウザーに組込みのJavaScript言語の上にある構造で、あなたが何かの機能をもっと簡単に実装できるようにします。
• サードパーティAPI — サードパーティのプラットフォーム(TwitterやFacebook)上に作られた構造で、それらのプラットフォームの機能をあなたのウェブページで利用できるようにします(例えばあなたの最新のツイートあなたのウェブページに表示する)。
• JavaScriptライブラリ — 多くは、独自の関数 を含んだ一つか複数のJavaScriptファイルで、あなたのウェブページにくっつけることでスピードアップしたり共通の機能を書いたりできるものです。例えば、jQuery、MootoolsやReactがなどが含まれます。
• JavaScriptフレームワーク — ライブラリの一階層上にあたり、JavaScriptフレームワーク(例えばAngularやEmber)はHTMLやCSSにJavaScript、インストールして一からウェブアプリケーションを作成するのに使えるその他もろもろの技術がパッケージ化されている場合が多いです。ライブラリとフレームワークの大きな相違点は、「制御の逆転(Inversion of Control)」にあります。ライブラリのメソッドを呼ぶ時には、開発者がコントロールしています。フレームワークでは、コントロールが逆転します: フレームワークから開発者のコードが呼ばれるのです。

APIで何ができる?

モダンなブラウザーではすごい数のAPI利用できるので、あなたのコードからとてもいろいろな事ができます。 MDN API索引を見てみればわかると思います。

一般的なブラウザーAPI

特に、あなたが使うであろう最も一般的なブラウザーAPIのカテゴリ(このモジュールでとても詳しい所まで網羅していきます)は:

• ブラウザーで読み込んだ文書を操作するためのAPI。一番目にする例はDOM (Document Object Model) APIで、HTMLとCSSを操作できます — HTMLを作成したり削除したり書き換えたり、動的に新しいスタイルをページに適用したり、などなど。 例えばページにポップアップウィンドウが表われたり、何か新しい中身が表示されたりする時、DOMが使われています。この種のAPIについてはドキュメントの操作でもっといろいろ見られます。
• サーバからデータ取得をするAPIでウェブページの一部を書き換える事はとてもよく行なわれます。この一見ちょっとした事が、サイトのパフォーマンスや振舞いに巨大なインパクトを与えました  — 在庫一覧や新しいお話一覧を書き換えたい時に、サーバからページ全体をリロードする事なしにさくっとできたら、サイトやアプリはずっと反応よく素早く感じられます。これを可能にしたAPIには XMLHttpRequest と Fetch API が含まれています。Ajaxという言葉を聞いた事があるかもしれませんが、これがこのテクニックの呼び名です。これらのAPIについて サーバからのデータ取得でもっといろいろ見られます。
• グラフィックスを描画したり操作するAPI は多くのブラウザーがサポートしています — 最も知られているものにはCanvas と WebGLがあり、HTMLの<canvas> 要素上にあるピクセルデータを書き換えて2次元や3次元のシーンを作成するのに使えます。例えばキャンバスAPIを使って長方形や円のような形を描いたり、キャンバスに画像を読み込んだり、セピアやグレイスケールといったフィルターを適用したり、あるいはWebGLを使ってライティングやテクスチャを使った3Dシーンを作成したりできます。これらのAPIはよくアニメーションループを作成するAPI(window.requestAnimationFrame()など)や他のものと組み合わせて使われ、アニメやゲームのようなものの表示を定期的に書き換えるようにします。
• 動画と音声のAPI HTMLMediaElementや Web Audio APIやWebRTCのようなAPIを使うと、 マルチメディアを使ってとても面白い事ができます。音声や動画再生のための独自のコントロールUIの作成、字幕やサブタイトルのような音声トラックをビデオと一緒に表示したり、ウェブカメラの画像を取り込んで操作し、上述のキャンバスに表示したりウェブカンファレンスに参加している他の誰かのコンピュータ上に表示したり、音声トラックにイフェクト(ゲイン、ディストーション、音場効果など)をかけたりできます。
• デバイスAPI は基本的にウェブアプリで使えるような形で、今時のハードウェアデバイスのデータを操作したり取得するAPIです。デバイスの位置データにアクセスして地図上にあなたの居場所を書くような位置情報APIについてはすでにお話しました。他の例にはシステム通知を使ってウェブアプリに役に立つアップデートがあるのを知らせたり(Notifications APIを参照)、ハードウェアを振動させたり(Vibration APIを参照)などがあります。
• クライアント側でのデータ保持API は今多くのブラウザーに普及しつつあります。— クライアント側にデータを保存できると、ページを移動しても状態を保存したり、たとえデバイスがオフラインでも動作するようなアプリを作成したいような場合、とても役に立ちます。いくつもの選択肢があり、例えばWeb Storage APIを使ったキーバリューストアや、 IndexedDB APIを使ったもっと複雑なテーブル型データ保存などです。

一般的なサードパーティAPI

サードパーティAPIはバラエティーに富んでいます。あなたが遅かれ早かれ使うようになりそうな、世間でよく使われているものには以下のようなものがあります:

• Twitter API、あなたの最新のツイートをあなたのウェブサイトに表示したりするような事に使えます。
• Google Maps API あなたのウェブページ上に地図を使ったあらゆる事(面白い事に、これはグーグルマップにとっても役立ちます)をやるのに使えます。今ではこれはAPIの完全体となり、Google Maps API Pickerが証明しているように、非常に様々なタスクを取り扱えるようになりました。
• Facebook APIスイートによってFacebookエコシステムの様々な部品を使ってあなたのアプリを強化できます。例えばアプリへのログインをFacebookのログインで行なったり、アプリ内での支払い、ターゲット広告を出したりなどです。
• YouTube APIを使ってあなたのサイトにYouTubeのビデオを埋め込んだり、YouTubeを検索したり、プレイリストを作成したりなどなどできます。
• Twilio APIはあなたのアプリで音声・ビデオ電話の機能を作成したり、SMS/MMSを送信したりなどするためのフレームワークを提供します。

APIはどのように動作する?

異なるJavaScript APIはそれぞれに違う方法で動作しますが、普通は、共通した機能とどのように動くべきかの類似したテーマを持ちます。

オブジェクトに基づいています

あなたのコードは一つ以上のJavaScriptオブジェクトを通じてAPIとやりとりし、オブジェクトはAPIが使用するデータ(オブジェクトのプロパティとして持つ)やAPIが提供する機能(オブジェクトメソッドとして持つ)の容れ物として使われます。

位置情報APIの例に戻りましょう — これは少数の単純なオブジェクトからなるとても簡単なAPIです:

• Geolocation、これには位置データ取得を制御するための三つのメソッドがあります。
• Position、これには指定された時点のデバイスの位置を表わします — これにはCoordinatesオブジェクトが含まれており、座標オブジェクトには実際の位置の情報と指定の時点を表わすタイムスタンプを含みます。
• Coordinatesには利用可能なデバイスの位置に関するデータがまるっと入っていて、緯度と経度、高度、速度、移動方向、などが含まれています。

ではこれらのオブジェクトがどう関連するのでしょう? 例maps-example.html を見ていただくと(ライブ実行も見てね)、次のようなコードがあります:

navigator.geolocation.getCurrentPosition(function(position) {
  var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
  var myOptions = {
    zoom: 8,
    center: latlng,
    mapTypeId: google.maps.MapTypeId.TERRAIN,
    disableDefaultUI: true
  }
  var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
});

まず最初に、私達のデバイスの現在位置を返すNavigator.geolocationプロパティを呼ぶとブラウザーのGeolocationオブジェクトにアクセスできるので、次のようにして始めます:

navigator.geolocation.getCurrentPosition(function(position) { ... });

これはこんな風にするのと等価です

var myGeo = navigator.geolocation;
myGeo.getCurrentPosition(function(position) { ... });

が、ドット記法でプロパティ/メソッドを一つに繋いでいくことで、書かねばならない行数を減らせます。

Geolocation.getCurrentPosition()メソッドに必須の引数は一つしかなく、これはデバイスの現在位置を上手く取得できた場合に走る匿名関数になります。この匿名関数自体の引数は一つで、現在の位置データを保持するPositionオブジェクトとなります。

処理が完了した時にだけ関数を呼び出すというパターンはJavaScript APIにおいて非常によく使われます — それが返すはずのデータを別の処理で使用する前に、ある処理が完了したことを確実にするためです。こういう方法を非同期処理と呼びます。何故ならデバイスの現在位置を取得する事は外部コンポーネント(デバイスのGPSや他の位置取得ハードウェア)に依存していて、データが即座に返されすぐに使用できるよう、処理が時間内に完了するという保証がないからです。ですからこのような方法は上手くいきません:

var position = navigator.geolocation.getCurrentPosition();
var myLatitude = position.coords.latitude;

もし最初の行がまだ結果を返していない場合、位置情報がまだ得られていないので、2行目はエラーを起すでしょう。この理由から、非同期処理が含まれるAPIではコールバック関数を使うか、もっと今風のPromisesシステム—これはECMAScript6で定義されていてより新しいAPIでは広く使用されています—を使うように設計されています。

私たちは位置情報APIと組み合わせてサードパーティーAPI — グーグルマップAPI — を getCurrentPosition() で返された地点をグーグルマップに表示するのに使いました。ページにリンクを作ってこのAPIが使えるようにします — HTML中にこの行があるでしょう:

<script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script>

APIを使うために、まずgoogle.maps.LatLng()コンストラクタを使ってLatLngオブジェクトインスタンスを作成しますが、これはCoordinates.latitudeとCoordinates.longitudeの値を引数に取ります:

var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);

このオブジェクト自体はmyOptionという名前にしたオプション指定オブジェクトのcenterプロパティの値に設定します。それから google.maps.Map()コンストラクタに二つの引数 — 地図を中に表示させたい<div>要素(map_canvasというIDを使って)への参照と、すぐ上で定義したオプション指定オブジェクト — を渡して呼び出し、地図を表わすオブジェクトのインスタンスを作成します。

var myOptions = {
  zoom: 8,
  center: latlng,
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  disableDefaultUI: true
}

var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);

これが完了すると、私たちの地図が表示されます。

このコードの最後の部分ハイライトは、多くのAPIで目にする事になる共通パターンが二つです。一つはAPIオブジェクトはたいていコンストラクタがあり、あなたのプログラムから使う用のインスタンスを作成するのに呼び出されます。二つめは、APIオブジェクトには、プログラムに必要な正確な環境を得るために調節できるよう、いくつかのオプションが用意されている事がよくある、という事です。APIコンストラクターはだいたい引数としてオプションオブジェクトを受理するので、これがそういったオプションをセットする場所になります。

認識できる入口があります

APIを使うときは、そのAPIの入口がどこなのかしっかり確認するべきです。位置情報APIではとても単純でした — それはNavigator.geolocation プロパティで、これはブラウザーのGeolocationを返し、使える位置情報用のメソッドを全部抱えています。

Document Object Model (DOM) APIでも単純な入口があります — これの機能はDocumentもしくはなんかしたいHTML要素にぶらさがっている場合が多く、例えば:

var em = document.createElement('em'); // create a new em element
var para = document.querySelector('p'); // reference an existing p element
em.textContent = 'Hello there!'; // give em some text content
para.appendChild(em); // embed em inside para

他のAPIではもう少し複雑な入口があり、APIコードを書き込むための固有のコンテキストを作成しなければならないものがよくあります。例えばキャンバスAPIのコンテキストオブジェクトは、描画をしたい<canvas>要素への参照を取得して、 これのHTMLCanvasElement.getContext()メソッドを呼ぶと作成されます:

var canvas = document.querySelector('canvas');
var ctx = canvas.getContext('2d');

キャンバスを使って何かやろうとする場合は何でも、コンテキストオブジェクト(これはCanvasRenderingContext2Dのインスタンスです)のプロパティやメソッドを呼んで行ないます。例えば:

Ball.prototype.draw = function() {
  ctx.beginPath();
  ctx.fillStyle = this.color;
  ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI);
  ctx.fill();
};

状態の変化を捉えるのにイベントを使います

すでに学習コース中でイベントについてはお話しています、イベントの紹介 — この記事でクライアント側ウェブイベントとは何か、コードの中でどのように使えるのか詳しく見てきました。もしまだクライアント側ウェブAPIの仕組みがよくわからいなら、この先に進む前に記事を読み直しておく方が良いでしょう。

イベントを持たないウェブAPIもあり、イベントがたくさんあるウェブAPIもあります。イベントが発火した際に関数を実行できるイベントハンドラーのプロパティについては、リファレンス記事の独立した"イベントハンドラー"セクションとしておおよそ列挙されています。 簡単な例として、XMLHttpRequest オブジェクトのインスタンス(一つ一つがサーバから何らかの新しいリソースを取得しようとするHTTPリクエストを表わします)にはとてもたくさんのイベントが付随しており、たとえば load イベントは要求したリソースに対する正常なレスポンスが返ってきて、それが使えるようになった時点で発火します。

次のコードはこれをどう使うのか示す簡単な例です:

var requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json';
var request = new XMLHttpRequest();
request.open('GET', requestURL);
request.responseType = 'json';
request.send();

request.onload = function() {
  var superHeroes = request.response;
  populateHeader(superHeroes);
  showHeroes(superHeroes);
}

最初の5行で取得したいリソースを指定し、XMLHttpRequest()コンストラクタを使って新しいリクエストオブジェクトを生成し、指定のリソースを取得するためにGETリクエストを作り、レスポンスをJSON形式として吐き出すよう指定、そしてリクエストを送信します。

onloadハンドラー関数で私たちがレスポンスに対して何を行なうかを指定します。loadイベントが起きるのはレスポンスが正常に得られた場合だけ(エラーは起きていない)とわかっていますので、JSONであるレスポンスをsuperHeroes変数に保存し、以降の処理のために二つの異なる関数に引き渡しています。

必要なところには追加のセキュリティ機構があります

ウェブAPI機能はJavaScriptや他のウェブ技術と同等のセキュリティ上の配慮が必要です(例えばsame-originポリシー)が、追加のセキュリティ機構が必要な場合もあります。例として今時のウェブAPIの中にはHTTPSで配信されるページ上でしか動かないものがあり、これは機密とすべきデータをやりとりする可能性があるためです(ServiceWorkersやPushなど)。

さらには、ある種のウェブAPIへの呼び出しがあなたのコードにあると、ユーザに対してそれの許可を要求します。例えば、以前やった位置情報 の例が読み込まれた時、次のようなダイアログが出ていたのに気付いたでしょう:

Notifications API(通知API) も類似の許可を要求します:

これらの許可要求プロンプトはユーザのセキュリティのためにあります — これらがその時に表示されないと、サイトはあなたに知らせることなくあなたの居場所を追跡しはじめたり、うざったい通知を送り付けまくったりできてしまいます。

まとめ

ここまで来れば、APIとは何か、どう動くのか、あなたのJavaScriptコードからどんな事ができるのかよくわかったと思います。どれかのAPIを使って楽しいことをやりたくってしょうがなくなってることと思いますんで、さあ始めましょう! 次から、Document Object Model(DOM)を使った文書の操作を見ていきます。

このモジュールの記事

• ウェブAPIの紹介
• ドキュメントの操作
• サーバからのデータ取得
• サードパーティAPI
• 絵を描く
• 動画と音声のAPI
• クライアント側でのデータ保持