Introducción a las APIs web

¿Qué son las APIs?

Las interfaces de programación de aplicaciones (APIs), son construcciones disponibles en los lenguajes de programación para permitir que los desarrolladores creen funcionalidades complejas con mayor facilidad. Abstraen el código más complejo, dándote una sintaxis más sencilla para usar en su lugar.

Como ejemplo del mundo real, piensa en el suministro eléctrico de tu casa, apartamento u otra vivienda. Si quieres usar un electrodoméstico en tu casa, lo conectas a un enchufe y funciona. No intentas conectarlo directamente al suministro eléctrico; hacerlo sería muy ineficiente y, si no eres electricista, difícil y peligroso de intentar.

Fuente de la imagen: Enchufe sobrecargado por The Clear Communication People, en Flickr.

De la misma manera, si quieres, por ejemplo, programar gráficos 3D, es mucho más fácil hacerlo usando una API escrita en un lenguaje de alto nivel como JavaScript o Python, en lugar de intentar escribir directamente código de bajo nivel (por ejemplo, C o C++) que controle directamente la GPU de la computadora u otras funciones gráficas.

APIs en JavaScript del lado del cliente

El JavaScript del lado del cliente, en particular, tiene muchas APIs disponibles; estas no forman parte del lenguaje JavaScript en sí, sino que están construidas sobre el lenguaje base de JavaScript, brindándote superpoderes adicionales para usar en tu código JavaScript. Por lo general, se dividen en dos categorías:

• Las APIs del navegador están integradas en tu navegador web y pueden exponer datos del navegador y del entorno informático circundante, y hacer cosas complejas y útiles con ellos. Por ejemplo, la Web Audio API proporciona construcciones de JavaScript para manipular audio en el navegador: tomar una pista de audio, alterar su volumen, aplicarle efectos, etc. Detrás de escena, el navegador en realidad usa código complejo de más bajo nivel (por ejemplo, C++ o Rust) para realizar el procesamiento de audio real. Pero, una vez más, esta complejidad queda abstraída de ti gracias a la API.
• Las APIs de terceros no vienen integradas en el navegador de forma predeterminada, y por lo general debes obtener su código e información desde algún lugar de la Web. Por ejemplo, la API de Google Maps te permite hacer cosas como mostrar un mapa interactivo de tu oficina en tu sitio web. Proporciona un conjunto especial de construcciones que puedes usar para consultar el servicio de Google Maps y obtener información específica.

Relación entre JavaScript, las APIs y otras herramientas de JavaScript

Arriba hablamos sobre qué son las APIs de JavaScript del lado del cliente y cómo se relacionan con el lenguaje JavaScript. Repasemos esto para que quede más claro, y mencionemos también dónde encajan otras herramientas de JavaScript:

• JavaScript: un lenguaje de scripting de alto nivel integrado en los navegadores que te permite implementar funcionalidad en páginas web/aplicaciones. Ten en cuenta que JavaScript también está disponible en otros entornos de programación, como Node.
• APIs del navegador: construcciones integradas en el navegador que se sitúan sobre el lenguaje JavaScript y te permiten implementar funcionalidad con mayor facilidad.
• APIs de terceros: construcciones integradas en plataformas de terceros (por ejemplo, Disqus, Facebook) que te permiten usar parte de la funcionalidad de esas plataformas en tus propias páginas web (por ejemplo, mostrar tus comentarios de Disqus en una página web).
• Bibliotecas de JavaScript: normalmente uno o más archivos de JavaScript que contienen funciones personalizadas que puedes incorporar a tu página web para acelerar o facilitar la escritura de funcionalidad común. Algunos ejemplos son jQuery, Mootools y React.
• Frameworks de JavaScript: el siguiente paso después de las bibliotecas, los frameworks de JavaScript (por ejemplo, Angular y Ember) suelen ser paquetes de HTML, CSS, JavaScript y otras tecnologías que instalas y luego usas para escribir una aplicación web completa desde cero. La diferencia clave entre una biblioteca y un framework es la "inversión de control". Al llamar a un método de una biblioteca, el desarrollador tiene el control. Con un framework, el control se invierte: el framework llama al código del desarrollador.

¿Qué pueden hacer las APIs?

Existe una enorme cantidad de APIs disponibles en los navegadores modernos que te permiten hacer una amplia variedad de cosas en tu código. Puedes comprobarlo echando un vistazo a la página índice de APIs de MDN.

APIs comunes del navegador

En particular, las categorías más comunes de APIs del navegador que usarás (y que cubriremos con mayor detalle en este módulo) son:

• APIs para manipular documentos cargados en el navegador. El ejemplo más obvio es la API DOM (Document Object Model), que te permite manipular HTML y CSS: crear, eliminar y cambiar HTML, aplicar dinámicamente nuevos estilos a tu página, etc. Cada vez que ves aparecer una ventana emergente en una página o algún contenido nuevo mostrarse, por ejemplo, eso es el DOM en acción. Descubre más sobre este tipo de APIs en Introducción al scripting del DOM.
• Las APIs que obtienen datos del servidor para actualizar pequeñas secciones de una página web por sí solas se usan muy comúnmente. Este detalle aparentemente pequeño ha tenido un enorme impacto en el rendimiento y comportamiento de los sitios: si solo necesitas actualizar una cotización de bolsa o una lista de noticias disponibles, hacerlo al instante sin tener que recargar toda la página desde el servidor puede hacer que el sitio o la aplicación se sienta mucho más ágil y "receptiva". La API principal usada para esto es la Fetch API, aunque el código más antiguo aún podría usar la API XMLHttpRequest. También es posible que te encuentres con el término AJAX, que describe esta técnica. Descubre más sobre este tipo de APIs en Cómo hacer solicitudes de red con JavaScript.
• Las APIs para dibujar y manipular gráficos cuentan con amplio soporte en los navegadores; las más populares son Canvas y WebGL, que te permiten actualizar de forma programática los datos de píxeles contenidos en un elemento HTML <canvas> para crear escenas 2D y 3D. Por ejemplo, podrías dibujar formas como rectángulos o círculos, importar una imagen al canvas y aplicarle un filtro como sepia o escala de grises usando la Canvas API, o crear una escena 3D compleja con iluminación y texturas usando WebGL. Este tipo de APIs suele combinarse con APIs para crear bucles de animación (como window.requestAnimationFrame()) y otras, para producir escenas en constante actualización como caricaturas y juegos.
• APIs de audio y video como HTMLMediaElement, la Web Audio API y WebRTC te permiten hacer cosas realmente interesantes con multimedia, como crear controles de interfaz personalizados para reproducir audio y video, mostrar pistas de texto como subtítulos junto con tus videos, capturar video de tu cámara web para manipularlo mediante un canvas (ver arriba) o mostrarlo en la computadora de otra persona en una videoconferencia, o agregar efectos a pistas de audio (como ganancia, distorsión, paneo, etc.).
• Las APIs de dispositivo te permiten interactuar con el hardware del dispositivo: por ejemplo, acceder al GPS del dispositivo para encontrar la ubicación del usuario usando la Geolocation API.
• Las APIs de almacenamiento del lado del cliente te permiten almacenar datos en el lado del cliente, para que puedas crear una aplicación que guarde su estado entre cargas de página, e incluso funcione cuando el dispositivo esté sin conexión. Hay varias opciones disponibles, por ejemplo, almacenamiento simple de nombre/valor con la Web Storage API, y almacenamiento de bases de datos más complejo con la IndexedDB API.

APIs comunes de terceros

Las APIs de terceros vienen en una gran variedad; algunas de las más populares que probablemente uses tarde o temprano son:

• APIs de mapas, como Mapquest y la API de Google Maps, que te permiten hacer todo tipo de cosas con mapas en tus páginas web.
• El conjunto de APIs de Facebook, que te permite usar varias partes del ecosistema de Facebook en beneficio de tu aplicación, como proporcionar inicio de sesión mediante Facebook login, aceptar pagos dentro de la aplicación, lanzar campañas publicitarias segmentadas, etc.
• Las APIs de Telegram, que te permiten insertar contenido de canales de Telegram en tu sitio web, además de brindar soporte para bots.
• La API de YouTube, que te permite insertar videos de YouTube en tu sitio, buscar en YouTube, crear listas de reproducción y más.
• La API de Pinterest, que proporciona herramientas para gestionar tableros y pines de Pinterest e incluirlos en tu sitio web.
• La API de Twilio, que proporciona un framework para integrar funcionalidad de llamadas de voz y video en tu aplicación, enviar SMS/MMS desde tus aplicaciones y más.
• La API de Disqus, que proporciona una plataforma de comentarios que se puede integrar en tu sitio.
• La API de Mastodon, que te permite manipular funciones de la red social Mastodon de forma programática.
• La API de IFTTT, que permite integrar múltiples APIs a través de una sola plataforma.

¿Cómo funcionan las APIs?

Las diferentes APIs de JavaScript funcionan de maneras ligeramente distintas, pero en general comparten características comunes y temas similares en su funcionamiento.

Se basan en objetos

Tu código interactúa con las APIs mediante uno o más objetos de JavaScript, que sirven como contenedores para los datos que usa la API (contenidos en las propiedades del objeto) y la funcionalidad que la API pone a disposición (contenida en los métodos del objeto).

Volvamos al ejemplo de la Web Audio API: esta es una API bastante compleja, que consiste en varios objetos. Los más evidentes son:

• AudioContext, que representa un grafo de audio que se puede usar para manipular el audio que se reproduce dentro del navegador, y cuenta con varios métodos y propiedades disponibles para manipular ese audio.
• MediaElementAudioSourceNode, que representa un elemento <audio> que contiene el sonido que quieres reproducir y manipular dentro del contexto de audio.
• AudioDestinationNode, que representa el destino del audio, es decir, el dispositivo de tu computadora que realmente lo emitirá, generalmente tus altavoces o audífonos.

Entonces, ¿cómo interactúan estos objetos? Si observas nuestro ejemplo sencillo de web audio (también puedes verlo en vivo), primero verás el siguiente HTML:

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

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

Primero que todo, incluimos un elemento <audio> con el que incrustamos un MP3 en la página. No incluimos ningún control predeterminado del navegador. Después incluimos un <button> que usaremos para reproducir y detener la música, y un elemento <input> de tipo range, que usaremos para ajustar el volumen de la pista mientras se reproduce.

A continuación, veamos el JavaScript de este ejemplo.

Comenzamos creando una instancia de AudioContext dentro de la cual manipularemos nuestra pista:

const audioCtx = new AudioContext();

Luego, creamos constantes que almacenan referencias a nuestros elementos <audio>, <button> e <input>, y usamos el método AudioContext.createMediaElementSource() para crear un MediaElementAudioSourceNode que representa la fuente de nuestro audio, el elemento <audio> desde el que se reproducirá:

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

const audioSource = audioCtx.createMediaElementSource(audioElement);

A continuación, incluimos un par de manejadores de eventos que sirven para alternar entre reproducir y pausar cuando se presiona el botón, y para restablecer la pantalla al inicio cuando la canción termina de reproducirse:

// reproducir/pausar audio
playBtn.addEventListener("click", () => {
  // verificar si el contexto está en estado suspendido (política de reproducción automática)
  if (audioCtx.state === "suspended") {
    audioCtx.resume();
  }

  // si la pista está detenida, reproducirla
  if (playBtn.getAttribute("class") === "paused") {
    audioElement.play();
    playBtn.setAttribute("class", "playing");
    playBtn.textContent = "Pausar";
    // si la pista se está reproduciendo, detenerla
  } else if (playBtn.getAttribute("class") === "playing") {
    audioElement.pause();
    playBtn.setAttribute("class", "paused");
    playBtn.textContent = "Reproducir";
  }
});

// si la pista termina
audioElement.addEventListener("ended", () => {
  playBtn.setAttribute("class", "paused");
  playBtn.textContent = "Reproducir";
});

Luego, creamos un objeto GainNode usando el método AudioContext.createGain(), que se puede usar para ajustar el volumen del audio que pasa a través de él, y creamos otro manejador de eventos que cambia el valor de la ganancia (volumen) del grafo de audio cada vez que se cambia el valor del control deslizante:

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

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

Lo último que hay que hacer para que esto funcione es conectar los diferentes nodos en el grafo de audio, lo cual se hace usando el método AudioNode.connect() disponible en cada tipo de nodo:

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

El audio comienza en la fuente, que luego se conecta al nodo de ganancia para que se pueda ajustar el volumen del audio. El nodo de ganancia luego se conecta al nodo de destino para que el sonido se pueda reproducir en tu computadora (la propiedad AudioContext.destination representa cualquiera que sea el AudioDestinationNode predeterminado disponible en el hardware de tu computadora, por ejemplo, tus altavoces).

Tienen puntos de entrada reconocibles

Al usar una API, debes asegurarte de saber cuál es el punto de entrada de la API. En la Web Audio API, esto es bastante sencillo: es el objeto AudioContext, que se debe usar para realizar cualquier manipulación de audio.

El Document Object Model (DOM) API también tiene un punto de entrada sencillo: sus funciones suelen encontrarse colgando del objeto Document, o de una instancia del elemento HTML que quieras afectar de alguna manera, por ejemplo:

const em = document.createElement("em"); // crear un nuevo elemento em
const para = document.querySelector("p"); // referenciar un elemento p existente
em.textContent = "¡Hola!"; // darle a em algo de contenido de texto
para.appendChild(em); // incrustar em dentro de para

La Canvas API también depende de obtener un objeto de contexto para manipular cosas, aunque en este caso es un contexto gráfico en lugar de un contexto de audio. Su objeto de contexto se crea obteniendo una referencia al elemento <canvas> sobre el que quieres dibujar, y luego llamando a su método HTMLCanvasElement.getContext():

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

Todo lo que queramos hacer en el canvas se logra entonces llamando a las propiedades y métodos del objeto de contexto (que es una instancia de CanvasRenderingContext2D), por ejemplo:

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

Frecuentemente usan eventos para manejar cambios de estado

Ya hablamos sobre los eventos anteriormente en el curso, en nuestro artículo Introducción a los eventos, que analiza en detalle qué son los eventos web del lado del cliente y cómo se usan en tu código. Si aún no estás familiarizado con cómo funcionan los eventos de las APIs web del lado del cliente, deberías ir a leer ese artículo primero antes de continuar.

Algunas APIs web no contienen eventos, pero la mayoría contiene al menos algunos. Las propiedades de manejador que nos permiten ejecutar funciones cuando se disparan los eventos generalmente se listan en nuestro material de referencia en secciones separadas de "Manejadores de eventos".

Ya vimos varios manejadores de eventos en uso en nuestro ejemplo de la Web Audio API más arriba:

// reproducir/pausar audio
playBtn.addEventListener("click", () => {
  // verificar si el contexto está en estado suspendido (política de reproducción automática)
  if (audioCtx.state === "suspended") {
    audioCtx.resume();
  }

  // si la pista está detenida, reproducirla
  if (playBtn.getAttribute("class") === "paused") {
    audioElement.play();
    playBtn.setAttribute("class", "playing");
    playBtn.textContent = "Pausar";
    // si la pista se está reproduciendo, detenerla
  } else if (playBtn.getAttribute("class") === "playing") {
    audioElement.pause();
    playBtn.setAttribute("class", "paused");
    playBtn.textContent = "Reproducir";
  }
});

// si la pista termina
audioElement.addEventListener("ended", () => {
  playBtn.setAttribute("class", "paused");
  playBtn.textContent = "Reproducir";
});

Cuentan con mecanismos de seguridad adicionales cuando corresponde

Las funciones de las WebAPI están sujetas a las mismas consideraciones de seguridad que JavaScript y otras tecnologías web (por ejemplo, la política de mismo origen), pero a veces cuentan con mecanismos de seguridad adicionales. Por ejemplo, algunas de las WebAPIs más modernas solo funcionarán en páginas servidas por HTTPS debido a que transmiten datos potencialmente sensibles (algunos ejemplos son Service Workers y Push).

Además, algunas WebAPIs solicitan permiso para habilitarse por parte del usuario una vez que se realizan llamadas a ellas en tu código. Como ejemplo, la Notifications API solicita permiso mediante un cuadro de diálogo emergente:

Las APIs Web Audio y HTMLMediaElement están sujetas a un mecanismo de seguridad llamado política de reproducción automática: esto básicamente significa que no puedes reproducir audio automáticamente cuando se carga una página, sino que debes permitir que tus usuarios inicien la reproducción de audio mediante un control como un botón. Esto se hace porque la reproducción automática de audio suele ser realmente molesta y no deberíamos someter a nuestros usuarios a ella.

Resumen

A estas alturas, deberías tener una buena idea de qué son las APIs, cómo funcionan y qué puedes hacer con ellas en tu código JavaScript. Probablemente estés emocionado por empezar a hacer cosas divertidas con APIs específicas, ¡así que vamos! A continuación, veremos las APIs de video y audio.

• Overview: Client-side web APIs
• Siguiente