¿Qué es una API?

Ejemplo de una API pública

Tomemos como ejemplo GitHub, el servicio donde los programadores guardan y comparten su código. Tiene un sitio web donde podemos ver perfiles y repositorios. Al hacer clic en los enlaces, accedemos a distintas páginas, como el perfil de un usuario, la página de un repositorio, la configuración de la cuenta, y más.

• https://github.com/octocat es la página de un usuario específico.
• https://github.com/octocat/Hello-World es la página de un repositorio específico.

Cada una de estas páginas devuelve HTML, que muestra la información tal como la vemos, con todos los elementos de diseño. El sitio web se puede abrir en cualquier dispositivo con un navegador. Pero muchos servicios, además del sitio web, tienen también una aplicación móvil que muestra la misma información, con una interfaz más conveniente adaptada a un teléfono.

La aplicación móvil, a diferencia del sitio web, se almacena y se ejecuta directamente en el teléfono. Y todo el aspecto visual también se describe dentro de la aplicación. Para que esta aplicación funcione, necesita datos limpios que no están en el teléfono, sino en los servidores del servicio. ¿Cómo se pueden cargar estos datos en el teléfono? Las direcciones normales de las páginas no nos sirven, ya que devuelven páginas HTML completas en lugar de datos.

Aquí es donde entra en juego la API. Muchos servicios proporcionan direcciones HTTP especiales que devuelven datos limpios en lugar de páginas web completas. GitHub tiene una API pública de este tipo. Estos datos se devuelven en un formato estructurado, generalmente JSON. Un servicio "empaqueta" los datos en formato JSON, y otro servicio que los solicita los "desempaqueta" y los utiliza internamente para mostrarlos. Veamos un ejemplo de solicitud de un usuario.

# Dirección que devuelve los datos de un usuario
https://api.github.com/users/octocat

# La respuesta es un JSON con la siguiente estructura (fragmento)
{
  "login": "octocat",
  "id": 583231,
  "name": "The Octocat",
  "html_url": "https://github.com/octocat",
  "public_repos": 8,
  "created_at": "2011-01-25T18:44:36Z"
}

Los valores de la respuesta cambian con el tiempo, y la respuesta real incluye más campos que este fragmento.

El propósito de esta API es proporcionar un acceso conveniente a los datos del servicio. Pueden utilizarla las aplicaciones del propio servicio y también otros programas. Por ejemplo, un portafolio personal puede mostrar tus repositorios consultando esta API.

Por cierto, muchos sitios web también usan una API para cargar sus propios datos. El navegador carga un código JavaScript que implementa la lógica de visualización y solicita datos al servidor (a través de la API).

GitHub tiene una sección de documentación para desarrolladores, donde se describen en detalle su API, las direcciones, los parámetros que se pueden pasar y los formatos de respuesta. Cualquier servicio con una API pública tiene una descripción similar, es decir, está disponible para su uso en Internet. Sin embargo, público no significa gratuito, ya que una API puede ser de pago y a menudo lo es. Por ejemplo, la API de X (antes Twitter) funciona hoy con créditos de pago por uso. La API de GitHub se puede consultar sin pagar, aunque con límites de solicitudes.

API HTTP

La API de GitHub es un ejemplo de una API HTTP, que funciona a través del protocolo HTTP, que es el protocolo utilizado por los navegadores para cargar y mostrar sitios web. HTTP es el método más común y conveniente para crear API para servicios públicos en Internet. Es el protocolo en el que se basa todo Internet y tiene un buen soporte en cualquier lenguaje de programación. Después de todo, es un protocolo simple que todos los desarrolladores web conocen de alguna forma.

Sin embargo, no todas las API HTTP son iguales. HTTP deja muchas decisiones en manos de los desarrolladores, por lo que diferentes API HTTP pueden diferir significativamente, por ejemplo, en el formato de los datos. El formato más popular es JSON, pero también se utiliza XML. XML y HTML se parecen mucho en apariencia, pero XML describe datos en lugar de su apariencia y disposición. Veamos un fragmento.

<!-- Solo un ejemplo de una API en Internet -->
<Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
</Contents>

Existen otros formatos, pero se utilizan mucho menos. En general, HTTP no limita el formato, se puede inventar y utilizar uno propio.

Además de los formatos, las API HTTP también difieren en cómo están estructuradas las direcciones. Por ejemplo, en Códica Básicos, cada tipo de datos tiene su propia dirección.

• https://basicos.codica.la/api/languages.json devuelve la lista de lenguajes con cursos.

Este tipo de API se conoce comúnmente como API REST. Se puede encontrar más información al respecto en otro artículo. A veces, una API se ve de tal manera que siempre tiene la misma dirección, pero se envían diferentes parámetros en la solicitud. Este enfoque tiene muchas variaciones, como json-rpc, graphql y otros. Por ejemplo, así se verían las direcciones.

# Todas las solicitudes se envían a esta dirección
https://some-site.com/api/rpc
https://some-site.com/api/rpc?param=value

Y finalmente, tenemos la API de Websocket, donde la interacción ocurre en tiempo real en ambas direcciones, a diferencia de los ejemplos anteriores, donde el cliente (quien usa la API) debe solicitar los datos. Con Websocket, se crean aplicaciones en tiempo real, como chats o juegos. En estas aplicaciones, los datos modificados en el servidor deben enviarse rápidamente a todos los clientes interesados.

Hoy también existen API de modelos de lenguaje (inteligencia artificial) que se usan a través de HTTP. El programa envía una solicitud con el texto y recibe una respuesta en formato JSON, igual que en los ejemplos anteriores.

No solo API HTTP

Las API no se limitan solo a HTTP. Por lo general, este tipo de API se encuentra dentro de un servicio, para la interacción entre sus componentes, cada uno de los cuales se comporta como un pequeño servicio. Estas API pueden utilizar otros protocolos, como TCP, o construirse sobre otros enfoques, como colas de mensajes o flujos. Algunas palabras clave para buscar son grpc, rabbitmq y kafka.