Введение в web APIs

Интерфейс прикладного программирования (Application Programming Interfaces, APIs) — это готовые конструкции языка программирования, позволяющие разработчику строить сложную функциональность с меньшими усилиями. Они "скрывают" более сложный код от программиста, обеспечивая простоту использования.

Для лучшего понимания рассмотрим аналогию с домашними электросетями. Когда вы хотите использовать какой-то электроприбор, вы просто подключаете его к розетке, и всё работает. Вы не пытаетесь подключить провода напрямую к источнику тока — делать это бесполезно и, если вы не электрик, сложно и опасно.

Image source: Overloaded plug socket by The Clear Communication People, on Flickr.

Точно также, если мы хотим, например, программировать 3D графику, гораздо легче сделать это с использованием API, написанных на языках высокого уровня, таких как JavaScript или Python.

Для JavaScript на стороне клиента, в частности, существует множество API. Они не являются частью языка, а построены с помощью встроенных функций JavaScript для того, чтобы увеличить ваши возможности при написании кода. Их можно разделить на две категории:

• API браузера встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, Web Audio API предоставляет конструкции JavaScript для работы с аудио в браузере, например,можно взять звуковую дорожку, изменить её громкость или применить к ней эффекты. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++ или Rust) для обработки звука, но, как было сказано выше, эти детали скрыты благодаря API.
• Сторонние API не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в интернете. Например, Twitter API позволяет размещать последние твиты (tweets) на вашем веб-сайте. В данном API определён набор конструкций, осуществляющих запросы к сервисам Twitter и возвращающих определённые данные.

Итак, выше мы поговорили о том, что такое JavaScript API клиентской части и как они связаны с языком JavaScript. Давайте теперь тезисно запишем основные понятия и определим назначение других инструментов JavaScript:

• JavaScript — Язык программирования сценариев высокого уровня, встроенный в браузер, позволяющий создавать функциональность веб-страниц/приложений. Отметим, что JavaScript также доступен на других программных платформах, таких как Node.js. Но пока не будем останавливаться на этом.
• API браузера (Browser APIs) — конструкции, встроенные в браузер, построенные на основе языка JavaScript, предназначенные для облегчения разработки функциональности.
• Сторонние API (Third party APIs) — конструкции, встроенные в сторонние платформы (такие как Twitter, Facebook) позволяющие вам использовать часть функциональности этих платформ в своих собственных веб-страницах/приложениях (например, показывать последние Твиты на вашей странице).
• Библиотеки JavaScript — Обычно один или несколько файлов, содержащих пользовательские (custom) функции. Такие файлы можно прикрепить к веб-странице, чтобы ускорить или предоставить инструменты для написания общего функциональности. Примеры: jQuery, Mootools и React.
• JavaScript фреймворки (frameworks) — cледующий шаг в развитии разработки после библиотек. Фреймворки JavaScript (такие как Angular и Ember) стремятся к тому, чтобы быть набором HTML, CSS, JavaScript и других технологий, после установки которого можно "писать" веб-приложение с нуля. Главное различие между фреймворками и библиотеками — "обратное направление управления" ( "Inversion of Control" ). Вызов метода из библиотеки происходит по требованию разработчика. При использовании фреймворка — наоборот, фреймворк производит вызов кода разработчика.

Широкое разнообразие API в современных браузерах позволяет наделить ваше приложение большими возможностями. Достаточно посмотреть список на странице MDN APIs index page.

В частности, к наиболее часто используемым категориям API (и которые мы рассмотрим далее в этом модуле) относятся :

• API для работы с документами, загруженными в браузер. Явный пример — DOM (Document Object Model) API, позволяющий работать с HTML и CSS — создавать, удалять и изменять HTML, динамически изменять вид страницы и т.д. Любое всплывающее окно на странице или появляющееся "на ходу" содержимое — всё это благодаря DOM. Узнайте больше об этой категории API на странице Работа с документами.
• API, принимающие данные от сервера, часто используются, чтобы обновить небольшие части веб-страницы. Эта, казалось бы, малая деталь оказывает огромное влияние на производительность и поведение сайтов, так как нет необходимости перезагружать всю страницу целиком, если вам нужно просто обновить список товаров или новых доступных историй. Это также сделает приложение или сайт более отзывчивым и "живым". Список API, благодаря которым это возможно, включает: XMLHttpRequest и Fetch API. Вы также могли встретить термин Ajax, описывающий эту технологию. Узнать больше об этой категории API на странице Получение данных от сервера.
• API для работы с графикой широко поддерживаются браузерами, самые популярные: Canvas и WebGL, позволяющие программно изменять данные о пикселях, содержащиеся в элементе HTML <canvas> для создания 2D и 3D изображений. Например, вы можете нарисовать фигуры, скажем, прямоугольники или круги, импортировать изображение в canvas и применить к нему фильтры, такие как сепия или оттенки серого с помощью Canvas API, или создать сложное 3D-изображение с освещением и текстурами, используя WebGL. Такие API часто используют в сочетании с API создания анимационных циклов (таких как window.requestAnimationFrame()) и другими для создания постоянно меняющегося изображения на экране, как в мультфильмах или играх .
• Аудио и Видео API как HTMLMediaElement, Web Audio API, и WebRTC позволяют делать действительно интересные вещи с мультимедиа. Например, создать собственный пользовательский интерфейс (User Interface, UI) для проигрывания аудио/видео, вывод на экран субтитров, записывать видео с веб-камеры для обработки в canvas (см. выше) или для передачи на другой компьютер в видео-конференции, применять звуковые эффекты к аудио-файлам (такие как gain, distortion, panning и т.д.).
• API устройств — в основном, это API для обработки и считывания данных с современных устройств удобным для работы веб-приложений образом. Например, Geolocation API позволяет считать данные о местоположении устройства. Другие примеры включают уведомление пользователя о появившемся обновлении для веб-приложения с помощью системных уведомлений (см. Notifications API) или вибрации (см. Vibration API (en-US)).
• API хранения данных на стороне пользователя приобретают всё большее распространение в веб-браузерах — возможность хранить информацию на стороне клиента очень полезна, когда необходимо создать приложение, которое будет сохранять своё состояние между перезагрузками страницы, или даже работать, когда устройство не в сети. В данный момент доступно немало таких API. Например, простое хранилище данных в формате имя/значение (name/value) Web Storage API или хранилище данных в формате таблиц IndexedDB API.

Существует множество сторонних API; некоторые из наиболее популярных, которые вы рано или поздно будете использовать, включают:

• Twitter API для добавления такой функциональности, как показ последних твитов на сайте.
• Google Maps API для работы с картами на веб-странице (интересно, что Google Maps также использует этот API). Теперь это целый набор API, который может справляться с широким спектром задач, как свидетельствует Google Maps API Picker.
• Набор Facebook API позволяет использовать различные части платформы Facebook в вашем приложении, предоставляя, например, возможность входа в систему с логином Facebook, оплаты покупок в приложении, демонстрация целевой рекламы и т.д.
• YouTube API, предоставляющий возможность встраивать видео с YouTube на вашем сайте, производить поиск, создавать плейлисты и т.д.
• Twilio API — фреймворк для встраивания функциональности голосовой и видео связи в вашем приложении, отправки SMS/MMS из приложения и т.д.

Работа разных JavaScript API немного отличается, но, в основном, у них похожие функции и принцип работы.

Взаимодействие с API в коде происходит через один или больше объектов JavaScript, которые служат контейнерами для информации, с которой работает API (содержится в свойствах объекта), и реализуют функциональность, которую предоставляет API (содержится в методах объекта).

Вернёмся к примеру с Web Audio API — это довольно сложный API, состоящий из ряда объектов. Наиболее очевидные из них

• AudioContext, представляющий аудиограф (en-US), который содержит ряд полезных свойств и методов для управления воспроизведением звука в браузере.
• MediaElementAudioSourceNode представляет элемент <audio>, включающий в себя звук, которым можно управлять внутри аудиоконтекста или воспроизвести.
• AudioDestinationNode (en-US) представляет место назначения звука, то есть устройство вашего компьютера, которые фактически выводит его. Обычно это динамики или наушники.

Так как же эти объекты взаимодействуют? Если вы посмотрите на наш пример simple web audio example (see it live also), вы увидите следующий код:

<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" />

Прежде всего, добавляем элемент audio, с помощью которого встраиваем MP3 на страницу. Мы не включаем какие-либо элементы управления по умолчанию. Далее добавляем элемент <button>, который будем использовать для воспроизведения и остановки музыки, и элемент <input> с типом range, он понадобится для регулировки громкости трека во время его воспроизведения.

Взглянем на JavaScript код этого примера.

Начнём с того, что создадим экземпляр конструктора AudioContext, с помощью которого будет манипулировать нашим треком.

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

Далее создадим константы для наших <audio>, <button> и <input> элементов и воспользуемся методом AudioContext.createMediaElementSource() для создания MediaElementAudioSourceNode, представляющий источник аудио, с которым будет воспроизводиться элемент audio.

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

const audioSource = audioCtx.createMediaElementSource(audioElement);

Затем включим пару обработчиков событий для переключения между воспроизведением и паузой при нажании на кнопку и сброса воспроизведения в начало, когда песня закончится:

playBtn.addEventListener("click", () => {
  // проверить, находится ли контекст в приостановленном состоянии
  if (audioCtx.state === "suspended") {
    audioCtx.resume();
  }

  // если трек остановлен, то начать его проигрывать
  if (playBtn.getAttribute("class") === "paused") {
    audioElement.play();
    playBtn.setAttribute("class", "playing");
    playBtn.textContent = "Pause";
    // если трек воспроизводится, приостановить проигрывание
  } else if (playBtn.getAttribute("class") === "playing") {
    audioElement.pause();
    playBtn.setAttribute("class", "paused");
    playBtn.textContent = "Play";
  }
});

// если трек закончился
audioElement.addEventListener("ended", () => {
  playBtn.setAttribute("class", "paused");
  playBtn.textContent = "Play";
});

Далее создадим объект GainNode (en-US) с помощью метода AudioContext.createGain() (en-US), который можно использовать для регулировки громкости звука, и еще один обработчик событий, с помощью которого будем менять значение усиления (громкости) в зависимости от значения <input type="range">.

// volume
const gainNode = audioCtx.createGain();

volumeSlider.addEventListener("input", () => {
  gainNode.gain.value = volumeSlider.value;
});

Наконец, чтобы всё заработало, соединим различные узлы в аудиографе с помощью метода AudioNode.connect() (en-US), доступном на каждом узле этого типа:

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

Звук начинается в источнике, который затем подключаетя к узлу усиления, чтобы можно было регулировать громкость звука. Затем узел усиления подключается к узлу назначения звука, чтобы его можно было воспроизвести на компьютере (по умолчанию свойство AudioContext.destination (en-US) равно значению AudioDestinationNode, которое имеет доступ к аудио-оборудованию компьютера, например, к динамикам).

При использовании API убедитесь, что вы знаете где точка входа для API. В Web Audio API это довольно просто — экземпляр констуктора AudioContext, возвращает объект, внутри которого доступны все полезные методы и свойства для манипуляции звуком.

Найти точку входа Document Object Model (DOM) API ещё проще — при применении этого API используется объект Document, или экземпляр элемента HTML, с которым вы хотите каким-либо образом взаимодействовать, к примеру:

const em = document.createElement("em"); // создаёт новый элемент em
const para = document.querySelector("p"); // ссылка на существующий элемент p
em.textContent = "Hello there!"; // присвоение текстового содержимого
para.appendChild(em); // встроить em внутрь para

Точки входа других API немного сложнее, часто подразумевается создание особого контекста, в котором будет написан код API. Например, объект контекста Canvas API создаётся получением ссылки на элемент <canvas>, на котором вы хотите рисовать. Затем необходимо вызвать метод HTMLCanvasElement.getContext():

const canvas = document.querySelector("canvas");
const ctx = canvas.getContext("2d");

Всё, что мы хотим сделать с canvas после этого, достигается вызовом свойств и методов объекта содержимого (content) (который является экземпляром 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 содержится ряд различных событий, в некоторых — событий нет. Свойства обработчика, позволяющие запускать функции при совершении какого-либо события по большей части перечислены в нашем материале отдельного раздела "Обработчики событий (Event handlers)".

Мы уже видели несколько обработчиков событий, используемых в нашем примере с Web Audio API выше:

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

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

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

Функциональность WebAPI подвержена тем же соображениям безопасности, что и JavaScript или другие веб-технологии (например, same-origin policy), но иногда они содержат дополнительные механизмы защиты. К примеру, некоторые из наиболее современных WebAPI работают только со страницами, обслуживаемыми через HTTPS в связи с передачей конфиденциальных данных (примеры: Service Workers и Push).

К тому же, некоторые WebAPI запрашивают разрешение от пользователя, как только к ним происходит вызов в коде. Например, Notifications API запрашивает разрешение для показа диалогого окна:

Web Audio и HTMLMediaElement API подчиняются механизму безопасности, который называется политикой автозапуска (en-US). Это означает, что вы не можете автоматически воспроизводить звук при загрузки страницы — вы должны разрешить своим пользователям инициировать воспроизведения звука с помощью какого-либо элемента управления, например, кнопки. Сделано это, потому что автовоспроизведение звука обычно очень раздражает, и мы не должны подвергать этому наших пользователей.

На данном этапе, у вас должно сформироваться представление о том, что такое API, как они работают и как вы можете применить их в своём JavaScript-коде. Вам наверняка не терпится начать делать по-настоящему интересные вещи с конкретными API, так вперёд! В следующий раз мы рассмотрим работу с документом с помощью Document Object Model (DOM).

• Обзор: Client-side web APIs
• Далее

• Введение в web APIs
• Manipulating documents
• Fetching data from the server
• Third party APIs
• Drawing graphics (en-US)
• Video and audio APIs (en-US)
• Client-side storage