Web API の紹介

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

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

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

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

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

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

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

ここまででクライアントサイド 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 を利用できるので、コードからとてもいろいろな事ができます。 MDN 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 はバラエティーに富んでいます。あなたが遅かれ早かれ使うようになりそうな、世間でよく使われているものには以下のようなものがあります:

• Twitter API、あなたの最新のツイートをあなたの Web サイトに表示したりするような事に使えます。
• Mapquest や Google Maps API のような地図の API は、あなたのWebページ上に地図を使ったあらゆる事を可能にします。
• Facebook APIスイートによって Facebook エコシステムの様々な部品を使ってあなたのアプリを強化できます。例えばアプリへのログインを Facebook のログインで行なったり、アプリ内での支払い、ターゲット広告を出したりなどです。
• Telegram APIs  を使用すると、ボットのサポートに加えて、Telegram チャネルのコンテンツを Web サイトに埋め込むことができます。
• YouTube APIを使ってあなたのサイトに YouTube のビデオを埋め込んだり、YouTube を検索したり、プレイリストを作成したりなどなどできます。
• Pinterest API は、Pinterest のボードとピンを管理して Web サイトに含めるためのツールを提供します。
• Twilio APIはあなたのアプリで音声・ビデオ電話の機能を作成したり、SMS/MMSを送信したりなどするためのフレームワークを提供します。
• Mastodon API を使用すると、Mastodon ソーシャルネットワークの機能をプログラムで操作できます。

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

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

Let's return to the example of the Web Audio API — this is a fairly complex API, which consists of a number of objects. The most obvious ones are:

• AudioContext, which represents an audio graph that can be used to manipulate audio playing inside the browser, and has a number of methods and properties available to manipulate that audio.
• MediaElementAudioSourceNode (en-US), which represents an <audio> element containing sound you want to play and manipulate inside the audio context.
• AudioDestinationNode, which represents the destination of the audio, i.e. the device on your computer that will actually output it — usually your speakers or headphones.

So how do these objects interact? If you look at our simple web audio example (see it live also), you'll first see the following HTML:

<audio src="outfoxing.mp3"></audio>

<button class="paused">Play</button>
<br>
<input type="range" min="0" max="1" step="0.01" value="1" class="volume">

We, first of all, include an <audio> element with which we embed an MP3 into the page. We don't include any default browser controls. Next, we include a <button> that we'll use to play and stop the music, and an <input> element of type range, which we'll use to adjust the volume of the track while it's playing.

Next, let's look at the JavaScript for this example.

We start by creating an AudioContext instance inside which to manipulate our track:

const AudioContext = window.AudioContext || window.webkitAudioContext;
const audioCtx = new AudioContext();

Next, we create constants that store references to our <audio>, <button>, and <input> elements, and use the AudioContext.createMediaElementSource() method to create a MediaElementAudioSourceNode representing the source of our audio — the <audio> element will be played from:

const audioElement = document.querySelector('audio');
const playBtn = document.querySelector('button');
const volumeSlider = document.querySelector('.volume');

const audioSource = audioCtx.createMediaElementSource(audioElement);

Next up we include a couple of event handlers that serve to toggle between play and pause when the button is pressed and reset the display back to the beginning when the song has finished playing:

// play/pause audio
playBtn.addEventListener('click', function() {
    // check if context is in suspended state (autoplay policy)
    if (audioCtx.state === 'suspended') {
        audioCtx.resume();
    }

  // if track is stopped, play it
    if (this.getAttribute('class') === 'paused') {
        audioElement.play();
        this.setAttribute('class', 'playing');
        this.textContent = 'Pause'
    // if track is playing, stop it
} else if (this.getAttribute('class') === 'playing') {
        audioElement.pause();
        this.setAttribute('class', 'paused');
        this.textContent = 'Play';
    }
});

// if track ends
audioElement.addEventListener('ended', function() {
    playBtn.setAttribute('class', 'paused');
    playBtn.textContent = 'Play';
});

Next, we create a GainNode (en-US) object using the AudioContext.createGain() method, which can be used to adjust the volume of audio fed through it, and create another event handler that changes the value of the audio graph's gain (volume) whenever the slider value is changed:

const gainNode = audioCtx.createGain();

volumeSlider.addEventListener('input', function() {
    gainNode.gain.value = this.value;
});

The final thing to do to get this to work is to connect the different nodes in the audio graph up, which is done using the AudioNode.connect() (en-US) method available on every node type:

audioSource.connect(gainNode).connect(audioCtx.destination);

The audio starts in the source, which is then connected to the gain node so the audio's volume can be adjusted. The gain node is then connected to the destination node so the sound can be played on your computer (the AudioContext.destination property represents whatever is the default AudioDestinationNode available on your computer's hardware, e.g. your speakers).

APIを使うときは、その API の入口がどこなのかしっかり確認するべきです。Web Audio APIではとても単純でした — それは AudioContext オブジェクトであり、あらゆる音声操作を行うために使用する必要があります。

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

const em = document.createElement('em'); // create a new em element
const 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

Canvas API は、諸々を操作するために使用するコンテキストオブジェクトの取得にも依存していますが、この場合は、音声コンテキストではなく描画コンテキストです。そのコンテキストオブジェクトは、描画をしたい <canvas> 要素への参照を取得して、 これのHTMLCanvasElement.getContext() (en-US) メソッドを呼ぶと作成されます:

const canvas = document.querySelector('canvas');
const 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 はいくつか持っています。イベントが発火した際に関数を実行できるイベントハンドラーのプロパティについては、リファレンス記事の独立した"イベントハンドラー"セクションとしておおよそ列挙されています。

上記の Web Audio API の例では、すでにいくつかのイベントハンドラーが使用されています。

別の例として、XMLHttpRequest オブジェクトのインスタンス (一つ一つがサーバから何らかの新しいリソースを取得しようとするHTTPリクエストを表わします) にはとてもたくさんのイベントが付随しており、たとえば load イベントは発火したリソースに対する正常なレスポンスが返ってきて、それが使えるようになった時点で発火します。

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

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

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

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

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

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

さらには、ある種のWebAPIへの呼び出しがあなたのコードにあると、ユーザに対してそれの許可を要求します。例えば、Notifications API (通知 API) はポップアップのダイアログボックスを用いて許可を要求します:

Web Audio および HTMLMediaElement API には、自動再生 (autoplay) ポリシー と呼ばれるセキュリティ機構が適用されます。これは、基本的に、ページの読み込み時に音声を自動的に再生できないことを意味します。ユーザーに次のことを許可する必要があります。ボタンのようなコントロールを介して音声再生を開始します。これは、音声の自動再生は通常非常に煩わしいものであり、ユーザーにそれを課すべきではないためです。

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

• Overview: Client-side web APIs
• 次のページ

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