"Consumo" de APIS

 Con este título pareciese que os voy a hablar de una riquísima merienda de los 80 y 90, pero no, en este caso, Una API (Interfaz de Programación de Aplicaciones) es un conjunto de reglas y protocolos que permite a las aplicaciones de software comunicarse entre sí, compartir datos y funcionalidades.

Para intentar explicar esto, para la gente a la que le suena más a la merienda, precisamente voy a usar una analogía de un restaurante.

Imagina que entras en un restaurante.

1. Tú (El Cliente): Eres la aplicación que quiere algo (por ejemplo, un programa de Python, una app móvil, o incluso una página web con JavaScript).
2. La Cocina (El Servidor): Es donde está todo lo bueno: los datos, la lógica de negocio, la base de datos. Es el "cerebro" que tiene la información que tú quieres. No puedes entrar directamente a la cocina a coger cosas.
3. El Menú (La Documentación de la API): Es una carta donde se explica qué platos (datos o servicios) puedes pedir. Te dice el nombre de cada plato, los ingredientes (los parámetros que necesitas especificar) y cómo viene presentado (el formato de la respuesta).
4. El Camarero (La API REST): Este es el personaje clave. El camarero es la API. Es el intermediario que toma tu pedido, se lo lleva a la cocina, y te trae la respuesta.

Vale, y ahora, ¿qué es lo de REST?

REST (Representational State Transfer) es simplemente un conjunto de reglas de etiqueta o un protocolo de buenas maneras que sigue el camarero para que la comunicación sea eficiente y todo el mundo se entienda. Define cómo debes hacer el pedido para que la cocina te entienda perfectamente.

Resumen de la analogía: Tú (el cliente) le haces un pedido (una solicitud HTTP) al camarero (API REST) según lo que pone en el menú (documentación), el camarero se lo lleva a la cocina (servidor), que prepara tu plato (los datos), y el camarero te lo sirve en la mesa (la respuesta).

La Solicitud HTTP (Los Ingredientes de un Pedido)

Para que tu pedido al camarero (la solicitud a la API) sea perfecto, debe estar bien formada. Se componen de lo que llamamos un verbo HTTP y un Endpoint.

1. El Endpoint (la dirección del restaurante y la mesa): Es la dirección única a la que tienes que enviar tu solicitud. Normalmente, es una URL como las siguientes:

• https://api.mitienda.com/v1/productos
• https://api.twitter.com/2/tweets/search/recent

2. El Verbo HTTP (la acción que quieres hacer): Esto le dice al camarero qué quieres hacer exactamente. Los verbos son como las palabras mágicas.

• GET (Coger/Obtener): El más común. Es como decir "Tráeme...". Se usa para solicitar y recuperar datos, sin modificar nada en el servidor.

Ejemplo: GET https://api.mitienda.com/v1/productos -> "Tráeme la lista de productos."

• POST (Enviar/Crear): Es como decir "Toma, guarda esto". Se usa para crear un nuevo recurso. Lleva un "cuerpo" (body) con la información del nuevo elemento.

Ejemplo: POST https://api.mitienda.com/v1/productos -> "Aquí tienes los datos de un producto nuevo, guárdalo en la cocina (base de datos)." (El cuerpo llevaría el nombre, precio, etc.).

• PUT/PATCH (Actualizar): Es como decir "Quiero modificar este plato que ya pedí". Se usa para actualizar un recurso existente. PUT suele ser para reemplazarlo completamente y PATCH para modificar solo una parte.

Ejemplo: PATCH https://api.mitienda.com/v1/productos/123 -> Con esto le decimos: "Cambia el precio del producto con ID 123 a 29.99€"

• DELETE (Borrar): Muy claro. "Borra este plato de la cuenta". Se usa para eliminar un recurso.

Ejemplo: DELETE https://api.mitienda.com/v1/productos/123 -> En este caso le pedimos que borre algo: "Elimina el producto con ID 123."

3. Los Headers (son las instrucciones especiales para el camarero): Son metadatos o información adicional sobre tu solicitud. Van "por detrás", no son el pedido en sí, sino instrucciones sobre cómo hacerlo.

• Authorization: La más importante. Es como mostrar tu carnet de socio o tu reserva. Lleva una credencial (normalmente un "API Key" o un token) que le dice al servidor "Oye, soy yo, tengo permiso para estar aquí".

Ejemplo: Authorization: Bearer TU_TOKEN_SECRETO_AQUI.

• Content-Type: Le dice al camarero en qué formato le estás entregando la información si estás haciendo un POST o PUT. Lo más común es application/json (hablaremos de JSON luego).

4. El Body (este es el cuerpo, el pedido en sí mismo): Solo se usa con POST, PUT y PATCH. Es donde metemos los datos que quieres enviar para crear o actualizar. Si en GET le dices "tráeme una pizza", en POST le dices "quiero crear una pizza con estos ingredientes: masa fina, extra de queso, jamón...".

La Respuesta HTTP (La Respuesta del Camarero)

El camarero siempre vuelve con una respuesta. Esta respuesta tiene dos partes fundamentales:

1. El Código de Estado HTTP (es el estado de tu pedido): Un número de 3 dígitos que te indica claramente si todo fue bien o si hubo un problema. Es crucial saber leerlos.

• Todo bien (2xx): 200 OK: Tu pedido llegó y tienes lo que querías. 201 Created: ¡Creado! Se ha creado un nuevo recurso con tu petición POST.
• Errores del Cliente (4xx): 400 Bad Request: Has hecho un pedido mal formado (falta un parámetro, el body está mal, etc.). 401 Unauthorized: No tienes permiso. Tu API Key o token es inválido. 403 Forbidden: Tienes credenciales, pero no suficientes permisos para hacer esa acción concreta. 404 Not Found: El recurso que pides (el endpoint o el ID del producto) no existe.
• Errores del Servidor (5xx): 500 Internal Server Error: El problema está en la cocina (el servidor). No es culpa tuya.

2. El Body de la Respuesta (Los Datos - El Plato): Aquí es donde vienen los datos que pediste. El formato más común (con diferencia), es JSON (JavaScript Object Notation). Es un formato muy fácil de leer tanto para humanos como para máquinas. Se parece a los objetos en JavaScript o los diccionarios en Python.

Ejemplo de respuesta a una petición GET a: https://api.mitienda.com/v1/productos/123:

json
{
  "id": 123,
  "nombre": "Zapatillas Running Ultra",
  "precio": 89.99,
  "enStock": true,
  "categorias": ["deporte", "running"]
}

¿CÓMO se Hace Este Consumo? (Programas y Código)

Aquí viene la parte práctica. "Consumir una API" significa, a nivel técnico, escribir código que envíe estas solicitudes HTTP y procese las respuestas.

1. Herramientas para Probar y Jugar (Fundamentales):

• Postman: Es el rey. Es una aplicación de escritorio que te permite construir solicitudes HTTP (GET, POST, etc.) de forma muy visual. Puedes poner los endpoints, los headers, el body, etc., y ver la respuesta. Es IMPRESCINDIBLE para probar APIs antes de escribir código.
• Thunder Client (una extensión de VSCode) es una alternativa similar.
• cURL: Es un comando que viene en la terminal (Linux y Mac) o en el Prompt de Windows. Es la forma más "pura" y universal de hacer una petición HTTP.

Ejemplo en bash:

curl -X GET "https://api.mitienda.com/v1/productos" -H "Authorization: Bearer TU_TOKEN"

2. Lenguajes de Programación para Automatizar (donde se usa de verdad):

En un trabajo real, no vas a estar haciendo peticiones a mano con Postman todo el día. Integrarás el consumo de la API en tu aplicación. Casi cualquier lenguaje moderno puede hacerlo.

• Python (El Más Amigable): Con la librería requests es absurdamente fácil.

python
import requests

url = "https://api.mitienda.com/v1/productos"
headers = {"Authorization": "Bearer TU_TOKEN"}

respuesta = requests.get(url, headers=headers) # Hace la solicitud GET

datos = respuesta.json() # Convierte la respuesta JSON en un diccionario de Python

for producto in datos['productos']:

    print(producto['nombre'], producto['precio'])

• JavaScript (para web y Node.js): Se usa la función fetch() (nativa) o librerías como axios.

javascript

// Con fetch (en un navegador o Node.js moderno)
fetch('https://api.mitienda.com/v1/productos', {
  headers: { 'Authorization': 'Bearer TU_TOKEN' }
})
.then(response => response.json())
.then(data => console.log(data));

Java, C#, PHP, Go, etc.: Todos tienen sus librerías (como HttpClient en Java, RestSharp en C#...) para hacer exactamente lo mismo.

Recapitulando, necesitamos que sepas:

1. Leer y entender una documentación técnica (el menú del restaurante).
2. Obtener datos de un servicio externo (usando GET).
3. Enviar datos para crear nuevos registros (usando POST).
4. Actualizar y borrar información existente (usando PUT/PATCH y DELETE).
5. Manejar la autenticación (usando API Keys o Tokens en los Headers).
6. Interpretar los códigos de respuesta para manejar errores correctamente.
7. Procesar los datos que vienen en formato JSON.
8. Usar herramientas como Postman para pruebas y un lenguaje de programación (como Python con requests) para integrar todo esto en una aplicación real.

Y hasta aquí el símil de hoy de las APIs con un restaurante. Espero que haya sido fácil de seguir.