Qué es una API: Entiéndalo como el menú de un restaurante

Al finalizar este tema

Podrás explicar en una frase qué es una API y comprenderás los conceptos de método, punto final y parámetro.

Cuando los desarrolladores hablan entre sí

"Con esta integración de API será suficiente", "¿Ya obtuviste la clave de esa API?", "Hagámoslo con REST API".

Estas palabras se mencionan decenas de veces al día. Pero cuando se pregunta qué es una API, a menudo se responde con evasivas como: "Eh... ¿intercambiar datos?". Vamos a aclararlo correctamente esta vez.

Imagina que vas a un restaurante

Cuando vas a un restaurante, no entras directamente a la cocina para abrir el refrigerador, sacar la carne, encender el fuego y cocinarla... Simplemente miras el menú y pides: "Por favor, el cerdo de barriga asada número 1".

Una API funciona exactamente igual.

En lugar de acceder directamente al servidor (la cocina), consultas la documentación del menú (API) que el servidor ha establecido previamente y realizas una solicitud según las reglas establecidas. El servidor solo ejecuta lo que está en el menú. No importa cuánto lo pidas, no hará nada que no figure en el menú.

API = Un acuerdo establecido por el servidor para intercambiar datos entre programas

Lo importante aquí es la palabra "establecido". Solo si realizas la solicitud siguiendo las reglas definidas por el servidor recibirás una respuesta.

Los 3 elementos de una solicitud API

Al hacer un pedido en un restaurante, también se mencionan tres cosas:

• Qué hacer — "Quiero pedir" / "Quiero cancelar"
• Dónde — "Para la mesa número 1"
• Información adicional — "Extra arroz, huevo pasado por agua"

Una solicitud API también consta de exactamente tres partes:

GET https://api.weather.com/today?city=seoul
│    │                              │
Method  Endpoint                   Parameter
(qué)   (dónde)                    (información adicional)

Veámoslo paso a paso.

Método: Indica la acción que se va a realizar, expresada con un verbo.

Endpoint: Es la dirección del servidor al que se enviará la solicitud, es decir, la URL.

Parámetro: Condiciones adicionales. Se pueden añadir después de un signo de interrogación, como en ?city=seoul, o incluir en el cuerpo de la solicitud cuando se utiliza el método POST.

Con solo conocer estos tres elementos, podrás utilizar cualquier API del mundo. De verdad.

Pruébalo en la práctica

Escribe exactamente lo siguiente en la barra de direcciones de tu navegador:

https://jsonplaceholder.typicode.com/users/1

Aquí se mostrarán una gran cantidad de datos en formato JSON. Estos son los datos del usuario ficticio número 1. Acabamos de realizar una llamada a la API. ¿No es algo sencillo?

Así es como se vería en JavaScript:

// Llamada a la API para obtener la información del usuario 1
const res = await fetch('https://jsonplaceholder.typicode.com/users/1');
const user = await res.json();
console.log(user.name);  // "Leanne Graham"

fetch: ingresa la URL (punto final), convierte la respuesta a formato JSON y extrae los datos que necesitas. Estas tres líneas son todo lo que necesitas para realizar la llamada a la API.

fetch: utiliza GET como método predeterminado, por lo que no es necesario especificarlo. Si quieres enviar datos mediante POST:

// Llamada a la API para registrar una nueva publicación
await fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Primer artículo', body: 'Hola' })
});

Cambia el método a POST e incluye los datos que se enviarán en el cuerpo de la solicitud.

Pública vs. Privada: ¿A quién se ofrece acceso?

No todas las API están disponibles para el público en general.

• API pública: Accesible para todos. El ejemplo de jsonplaceholder que vimos antes es una API pública.
• API privada: Solo para uso interno de la empresa. No se ofrece acceso externo.
• API de socio: Compartida únicamente entre empresas que tienen un acuerdo.

Las API de traducción de Naver Papago y las API de mapas de Kakao son públicas, pero requieren que se obtenga una clave de API para poder usarlas. Si se utilizan sin una clave, se bloqueará el acceso.

¿Por qué se exige una clave? Porque si se permitiera el uso gratuito e ilimitado, los servidores se sobrecargarían. Por lo tanto, existen muchos modelos de pago, como "gratis hasta 1000 solicitudes diarias, y luego se cobra por cada solicitud adicional". Papago, Clova y Google Translate funcionan de esta manera.

Concepto clave

Una API es como un menú que define el servidor. No se puede solicitar algo que no esté en el menú, y las solicitudes deben seguir estrictamente el formato especificado. Método (qué acción realizar) + Endpoint (a dónde enviar la solicitud) + Parámetro (condiciones adicionales): con estos tres elementos es suficiente.