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

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

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

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

API で何ができる?

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

一般的なブラウザ API

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

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

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

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

• Twitter API、あなたの最新のツイートをあなたのWebサイトに表示したりするような事に使えます。
• Google Maps API あなたのWebページ上に地図を使ったあらゆる事(面白い事に、これはグーグルマップにとっても役立ちます)をやるのに使えます。今ではこれは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();
};

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

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

イベントを持たないWebAPIもあり、イベントがたくさんあるWebAPIもあります。イベントが発火した際に関数を実行できるイベントハンドラーのプロパティについては、リファレンス記事の独立した"イベントハンドラー"セクションとしておおよそ列挙されています。 簡単な例として、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変数に保存し、以降の処理のために二つの異なる関数に引き渡しています。

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

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

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

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

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

まとめ

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

このモジュール

• Web API の紹介
• ドキュメントの操作
• サーバからのデータ取得
• サードパーティ API
• グラフィックの描画
• 動画と音声の API
• クライアント側ストレージ