API 101: Una introducción básica a las API

API significa Interfaz de programación de aplicaciones. Significa exactamente lo que dice: hay interfaces entre programas y estas interfaces permiten que esos programas se comuniquen. Cuando los programadores desarrollan aplicaciones de software, a menudo necesitan su software para comunicarse con otro software o hardware. La API define el qué, cómo, cuándo, dónde y por qué de esas comunicaciones e interacciones.

Las API son una forma de resolver los desafíos empresariales con software. En la mayoría de las empresas, eso es un esfuerzo colaborativo. La colaboración siempre es más sencilla gracias a una comprensión compartida de los términos, conceptos y pasos clave.

Si piensa en hacer clic en un vínculo de una página web, el explorador utiliza bastantes API al hacer clic en el vínculo. El explorador reconoce el clic, realiza la solicitud de la página que desea visitar, recupera la página a través de Internet y, a continuación, la muestra en la pantalla. Hay muchos pasos más pequeños en el medio, pero su navegador es software que se comunica e interactúa con una variedad de API solo para mostrarle una página web. En este artículo resaltaremos términos, conceptos y pasos que son importantes al usar o discutir las API.

Al final de este artículo debería tener una comprensión clara de estos términos, conceptos y pasos fundamentales. La documentación de la API puede ser extensa y los debates sobre el uso de las API para abordar casos de uso específicos pueden ser muy detallados. Navegar por la documentación y discutir las API es más fácil y productivo, con fundamentos claros y una comprensión compartida.

Términos y conceptos de API

¿Qué significa una palabra o frase, y cómo puedo pensar en ello simple y fácilmente? En una API, la parte "aplicación" significa una aplicación de software o programa. La parte "interfaz de programación" hace referencia a cómo y dónde interactúa una aplicación con otra aplicación para determinados fines. En el ejemplo de nuestra página web, al hacer clic en un vínculo, el explorador envía una solicitud a un servidor para la página web.

En esta captura de pantalla, el cursor del ratón se sitúa sobre el vínculo de Adobe Experience Platform. En la parte inferior se encuentra la barra de estado del navegador web que muestra la "dirección" de la página que recibirá el navegador. En otras palabras, al hacer clic en el vínculo de Adobe Experience Platform, se indica al explorador que "obtenga esa página para que pueda verla aquí en mi pantalla".

Al hacer clic en un vínculo, el explorador realiza una solicitud a un servidor para obtener una página. Este es un GET La solicitud de, uno de los métodos de solicitud utilizados comúnmente con las API web. Una cosa que el navegador necesita para cumplir la solicitud es la página "dirección" - ¿dónde está en la web?

Partes de una dirección URL

La mayoría de los navegadores tienen una "barra de direcciones" que muestra parte o toda la "dirección" de una página web. Cuando el navegador "obtiene" la página para el enlace en el que hemos hecho clic, muestra la "dirección" de la página en esta barra de direcciones. Entonces, ¿cuál es la "dirección" de una página web?

Que https://business.adobe.com/products/experience-platform/adobe-experience-platform.html arriba se encuentra la dirección de una página en la web, que se denomina URL o Localizador uniforme de recursos. Las direcciones URL pueden hacer referencia a una página como esta, a un archivo de imagen, a un vídeo u otros tipos de archivo.

Esta dirección, la URL, tiene partes específicas que son muy relevantes para las API web y del explorador.

Esquema

El scheme lo anterior también se denomina protocol con las API web y, normalmente, http o https. El protocolo de transferencia HTTP o HyperText es la forma en que los recursos, como las páginas web, se transfieren de un servidor web a un explorador web. HTTPS es la versión segura, en la que la transferencia se produce a través de Internet mediante la seguridad destinada a evitar interferencias con el recurso que se transfiere. Es común ver un pequeño icono de candado en la barra de direcciones del navegador cuando se visualiza una página a través de HTTPS.

Para las API web, las transferencias de estos recursos se producen a través de solicitudes HTTP: solicitudes a través de HTTP, en otras palabras.

Hosts y dominios

El business.adobe.com es el host del recurso que se solicita. Cuando se hace clic en el vínculo de ejemplo, el explorador utiliza esta parte de la dirección URL para encontrar el servidor en el que está alojada la página. No siempre es exactamente lo mismo que el servidor web, pero en un nivel básico podemos pensarlo como el servidor donde el navegador obtendrá la página que solicitamos.

Los nombres de dominio forman parte del Sistema de nombres de dominio, más conocido como DNS. La mayoría piensa en adobe.com o example.com como "nombre de dominio", pero hay partes relevantes para las API. www.adobe.com y business.adobe.com pueden llamarse nombres de dominio, pero la variable www. y el business. Las partes de se denominan subdominios. Las API suelen interactuar con una dirección URL que incluye un subdominio como api.example.com o sub.www.example.com.

Es muy común ver el término host hacer referencia a un nombre de dominio completo, incluidos los subdominios como business.adobe.com. También es común ver los términos sector o nombre de dominio al hacer referencia a un host sin el subdominio como adobe.com. Memorizar los términos específicos de cada parte y variación de un host no es importante aquí. Sin embargo, tener en cuenta que estos términos se utilizan comúnmente es importante para que pueda aclarar cualquier detalle relevante para su negocio y discusiones.

Origen

Origen es otro término que hay que tener en cuenta que está estrechamente relacionado con las partes de una dirección URL. En un nivel básico, un origen es aproximadamente el scheme más el host más el domain gustar https://business.adobe.com. Los distintos valores suelen representar orígenes diferentes, como https://business.adobe.com y http://business.adobe.com no son del mismo origen porque tienen esquemas diferentes. https://www.adobe.com y https://business.adobe.com tampoco son el mismo origen en muchos usos debido a los diferentes subdominios.

Ruta

El último bit del ejemplo de URL anterior es el path al recurso: la página de nuestro ejemplo. El /products/experience-platform/ Esta parte suele representar carpetas o directorios en el servidor web. Al igual que tenemos carpetas o directorios en nuestros equipos para documentos y fotos, también tenemos carpetas en servidores web para organizar el contenido. Y finalmente, el /adobe-experience-platform.html part es el nombre del fichero: la página web.

Hay otras partes más detalladas de una URL que se resaltarán en la siguiente parte de esta serie.

API de terceros

Las API web a veces se denominan API de terceros. Piense en esto como en las partes involucradas en una transacción. En nuestro ejemplo de vínculo, usted (o más específicamente, su explorador) es el primero en la solicitud de la página. El servidor web es de segundo nivel. Entonces, ¿dónde está la tercera?

Es habitual que una página web incluya contenido o recursos de otros hosts o fuentes. En estos casos, cuando el navegador comienza a mostrar la página, realiza otro conjunto de solicitudes a esos otros hosts, o "terceros", que alojan esos recursos. Esto es muy común, especialmente para contenido multimedia como vídeos o imágenes, pero también para datos que deben actualizarse en el momento en que se ven o utilizan. Obtener la hora actual del día, el clima actual o un mensaje de bienvenida personalizado para una persona específica son ejemplos en los que una API de terceros puede proporcionar el recurso adecuado en el momento adecuado. Es común que estas solicitudes provengan de estas API de terceros.

Usos comunes de las API web

Aparte de la hora del día, el tiempo o el contenido personalizado, hay muchos usos para las API web. Las plataformas de medios sociales como Twitter, TikTok, Facebook, LinkedIn, Snapchat, Pinterest y otras tienen una variedad de API que los programadores pueden utilizar con sus aplicaciones. Y por supuesto, el Adobe también tiene una amplia variedad de API que los programadores utilizan para que su software pueda interactuar con los productos y servicios de Adobe. Los productos y servicios de software acceden a otros productos y servicios de software a través de estas API.

API de ejemplo

Las API de explorador permiten a los programadores interactuar directamente con las funciones del explorador. La API de batería permite que el software compruebe el estado de la batería de un dispositivo para que pueda avisarle si es necesario. La API del portapapeles permite al software copiar o pegar con el portapapeles del dispositivo. La API de pantalla completa permite al software presentar la opción para expandir la vista a la pantalla completa del dispositivo, como YouTube.

La API de acceso a datos de Adobe Experience Platform es una API web que permite a los programadores acceder y descargar archivos de conjuntos de datos de Adobe Experience Platform para que puedan utilizar los datos de perfil del cliente en sus propios programas. Es muy común que las API como esta formen parte de un proceso de automatización de software en el que el software está programado para realizar una secuencia de pasos utilizando varias API en combinación. Esto suele suponer un ahorro de costes significativo en comparación con la realización manual de estos mismos pasos.

Extremos de API

Cuando los programadores "utilizan" un navegador o API web en sus programas, suelen realizar solicitudes para enviar o recibir recursos, como nuestro explorador de ejemplo que solicita una página web. La documentación de la API a menudo enumera los "extremos" para esas solicitudes, por ejemplo: https://platform.adobe.io/data/foundation/export/files/{dataSetFileId}. Este es el patrón específico o "extremo" de la API de acceso a datos de Platform que utilizará un programador para obtener un archivo de conjunto de datos.

El {dataSetFileId} rodeado de llaves representa un valor que el programador necesita enviar en la solicitud. Por lo tanto, la dirección URL de la solicitud de API real tendría un aspecto similar al siguiente https://platform.adobe.io/data/foundation/export/files/xyz123brb donde el xyz123brb debe ser un ID válido del archivo del conjunto de datos que el programador desea recibir.

En otras palabras, del mismo modo que el explorador obtiene una página en una dirección URL específica, las solicitudes de API obtienen recursos de un extremo específico, o los envían a, como este ejemplo de conjunto de datos.

Métodos de solicitud HTTP

En este punto, debería quedar claro que las API web realizan solicitudes de recursos como páginas web o conjuntos de datos. Al igual que la mayoría de los conceptos de software, estas solicitudes HTTP siguen patrones repetibles. Se envía una solicitud desde una aplicación de software a otra aplicación de software que evalúa la solicitud y, a continuación, responde: el explorador solicita una página de un servidor web y responde con el contenido de la página.

Todo el proceso, desde la solicitud hasta la respuesta, implica muchos pasos más pequeños y muy detallados, pero los métodos de solicitud son sencillos. Los métodos de solicitud definen la operación que se solicita.

GET

El GET el método de solicitud se utiliza al solicitar una respuesta que proporciona un recurso, como nuestra página web y ejemplos de conjuntos de datos. Cuando hacemos clic en un vínculo en un explorador o tocamos un vínculo en un dispositivo móvil, estamos realizando una GET solicitud entre bastidores.

POST

El POST envía datos con la solicitud. Puede sonar extraño que una "solicitud" envíe datos, pero la idea es que al realizar la solicitud de API se pida al punto de conexión (el software receptor) que acepte la solicitud, y en el caso de un POST, para aceptar también los datos que se envían. Los datos enviados se suelen escribir en un almacén de datos, como una base de datos o un archivo, para poder guardarlos.

PUT

El PUT el método de solicitud es similar a POST dado que envía datos, pero si los datos que se están enviando ya existen en el extremo, un PUT actualizará los datos existentes reemplazándolos. A POST no se actualiza, simplemente envía, por lo que varias POST Las solicitudes de pueden crear varios registros de los datos enviados, en lugar de actualizar cualquier registro existente.

PATCH

El PATCH El método de solicitud se utiliza para enviar datos que actualizan parte de un registro existente, como cuando cambiamos nuestra dirección al actualizar nuestro perfil de cuenta. Con un POST solicitud se podría crear un perfil adicional y con un PUT, el perfil existente podría reemplazarse, pero utilizando el PATCH método simplemente actualizamos la parte relevante del registro existente, como nuestra dirección.

DELETE

El DELETE El método de solicitud elimina un recurso especificado en la solicitud, como si hacemos clic en un vínculo para eliminar completamente nuestro perfil de cuenta.

Hay varios más, pero esta es una lista de los métodos más comunes al trabajar con API.

Solicitar ejemplo

Ahora que tiene los términos, conceptos y pasos básicos involucrados con las API, podemos ver un ejemplo de solicitud de API en la práctica.

La página del ejemplo de explorador tiene una URL de https://business.adobe.com/products/experience-platform/adobe-experience-platform.html. Cuando se hace clic en el vínculo de Adobe Experience Platform, el explorador realiza una GET para esta página. Como tenemos el navegador para hacer el trabajo por nosotros, todo lo que tenemos que hacer es hacer clic, pero si un programador quiere que esa solicitud se produzca en una aplicación de software, tiene que proporcionar todos los detalles necesarios para que la solicitud de API se cumpla con éxito.

Este es el aspecto que podría tener el código:

fetch(
  "https://business.adobe.com/products/experience-platform/adobe-experience-platform.html",
  {
    headers: {
      accept:
        "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
      "accept-language": "en-US,en;q=0.9",
      "sec-ch-ua":
        '" Not A;Brand";v="99", "Chromium";v="101", "Microsoft Edge";v="101"',
      "sec-fetch-dest": "document",
      "sec-fetch-mode": "navigate",
      "sec-fetch-site": "none",
      "sec-fetch-user": "?1",
      "upgrade-insecure-requests": "1",
    },
    referrerPolicy: "strict-origin-when-cross-origin",
    body: null,
    method: "GET",
    mode: "cors",
    credentials: "include",
  }
);

En el código anterior, puede ver el URL el explorador solicita y, cerca de la parte inferior, está el method: "GET" método de solicitud. Las otras líneas de código también son partes de la solicitud, pero están fuera del ámbito de este artículo.