Tu primera petición a una API REST es tan sencilla como escribir una dirección en tu navegador, solo que con más control sobre lo que envías y recibes.
El momento en que todo cobra sentido
Era un martes por la tarde en las oficinas de una startup de logística en Guadalajara. Andrea, desarrolladora junior con tres meses en el puesto, llevaba dos semanas estudiando teoría sobre APIs REST: métodos HTTP, códigos de estado, autenticación. Lo entendía todo en papel. Pero cuando su líder técnico le dijo "conéctate a la API de rastreo y tráeme el estatus de este envío", su mente se quedó en blanco. Sabía qué era una API. No sabía cómo hablar con una.
Ese momento —entre la teoría y la acción— es donde la mayoría de las personas se atoran. Y lo curioso es que la solución es mucho más cercana de lo que parece.
Por qué la primera petición parece difícil (y no lo es)
El obstáculo real no es técnico. Es mental. Creemos que necesitamos escribir código complejo antes de poder ver algo funcionar. Pero existen herramientas diseñadas exactamente para eliminar esa barrera.
Dos de las más usadas en equipos profesionales de México y el mundo son Postman y curl. Postman es una aplicación con interfaz gráfica. curl es una herramienta de línea de comandos. Ambas te permiten enviar peticiones HTTP a cualquier API sin escribir una sola línea de código de programación. Solo describes qué quieres pedir, y ellas lo piden por ti.
Según datos de la empresa detrás de Postman, más de 30 millones de desarrolladores usan esta herramienta activamente. No es un accidente: es la forma más rápida de entender cómo responde una API antes de integrrarla en un proyecto real.
Tu primer contacto: una API pública real
Vamos a usar una API pública que no requiere autenticación. Se llama Open Meteo y devuelve datos del clima. Es gratuita, está disponible para cualquier persona y es perfecta para practicar.
La URL base es:
https://api.open-meteo.com/v1/forecast
Puedes pedirle el pronóstico del tiempo para Ciudad de México con esta URL completa:
https://api.open-meteo.com/v1/forecast?latitude=19.4326&longitude=-99.1332¤t_weather=true
Esa URL tiene tres partes importantes. Primero, la dirección base del servidor. Segundo, el endpoint /v1/forecast que indica qué recurso quieres. Tercero, los parámetros de consulta (latitude, longitude, current_weather) que personalizan tu petición.
Cómo hacerlo con Postman
Postman convierte una petición HTTP en algo visual. Descárgalo desde su sitio oficial y sigue estos pasos.
Abre Postman y crea una nueva pestaña de petición. En el menú desplegable de la izquierda verás los métodos HTTP: GET, POST, PUT, DELETE. Selecciona GET. Pega la URL del clima de CDMX en el campo de dirección. Haz clic en el botón azul Send.
En menos de dos segundos, verás la respuesta aparecer en la parte inferior de la pantalla. Algo parecido a esto:
{
"latitude": 19.4,
"longitude": -99.125,
"current_weather": {
"temperature": 22.4,
"windspeed": 14.2,
"weathercode": 1,
"time": "2024-03-15T14:00"
}
}
Postman también te muestra el código de estado HTTP en la esquina superior derecha de la respuesta. Si ves 200 OK, la petición fue exitosa. Si ves 400, algo en tu URL está mal formado. Si ves 404, el endpoint no existe.
Eso es todo. Acabas de hablar con una API real.
Cómo hacerlo con curl
curl es la herramienta favorita de quienes trabajan en servidores Linux o quieren automatizar peticiones desde la terminal. En México, muchos equipos de backend en empresas como FEMSA o Mercado Libre usan curl para probar integraciones rápidamente sin abrir ninguna interfaz gráfica.
Abre tu terminal (en Mac o Linux ya viene instalado; en Windows puedes usar Git Bash o la terminal de PowerShell moderna). Escribe:
curl "https://api.open-meteo.com/v1/forecast?latitude=19.4326&longitude=-99.1332¤t_weather=true"
Verás la misma respuesta JSON directamente en tu pantalla. Si quieres que el JSON se vea ordenado y con sangría, agrega el flag -s y pásalo por python3 -m json.tool:
curl -s "https://api.open-meteo.com/v1/forecast?latitude=19.4326&longitude=-99.1332¤t_weather=true" | python3 -m json.tool
Esto es especialmente útil cuando trabajas en servidores remotos donde no tienes acceso a una interfaz gráfica.
Agregar encabezados a tu petición
Algunas APIs requieren encabezados HTTP adicionales. Recuerda la lección anterior: muchas APIs usan el encabezado Authorization para verificar tu identidad con un token Bearer.
En Postman, haz clic en la pestaña Headers dentro de tu petición. Ahí puedes agregar pares de clave-valor. Por ejemplo:
Key: Authorization
Value: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
En curl, usas el flag -H para agregar encabezados:
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
https://api.ejemplo.com/pedidos
Cada -H adiciona un encabezado nuevo. Puedes poner tantos como necesites.
Cómo enviar una petición POST con datos
Hasta ahora solo hemos pedido información. Pero ¿qué pasa cuando necesitas enviar datos? Imagina que estás integrando el catálogo de productos de una tienda Liverpool en un sistema interno. Necesitas crear un nuevo producto enviando sus datos al servidor.
Eso se hace con el método POST y un cuerpo (body) en formato JSON.
En Postman: selecciona POST en el menú desplegable. Ve a la pestaña Body. Selecciona la opción raw y elige JSON en el menú de formato. Escribe tu objeto JSON:
{
"nombre": "Cafetera espresso",
"precio": 2499,
"categoria": "electrodomesticos",
"stock": 50
}
Haz clic en Send. El servidor recibirá esos datos y, si todo está bien, responderá con un 201 Created y el objeto que acaba de guardar.
En curl, el equivalente es:
curl -X POST https://api.ejemplo.com/productos \
-H "Content-Type: application/json" \
-H "Authorization: Bearer tu_token_aqui" \
-d '{"nombre": "Cafetera espresso", "precio": 2499, "categoria": "electrodomesticos", "stock": 50}'
El flag -X POST indica el método. El flag -d indica el cuerpo de la petición. El encabezado Content-Type: application/json le dice al servidor en qué formato estás enviando los datos.
Errores comunes al hacer tu primera petición
El error más frecuente es olvidar el encabezado Content-Type en peticiones POST. El servidor recibe tus datos pero no sabe cómo leerlos. El resultado es un error 400 confuso que parece indicar que tus datos están mal, cuando en realidad el problema es de formato.
El segundo error más común es confundir parámetros de consulta con el cuerpo de la petición. Los parámetros van en la URL (después del ?) en peticiones GET. El cuerpo va en el body en peticiones POST o PUT. Mezclarlos genera respuestas vacías o errores 422.
El tercer error es no revisar el código de estado de la respuesta. Muchos principiantes solo miran el cuerpo de la respuesta. Pero el código de estado te dice exactamente qué pasó: 401 significa que tu token está mal o expiró, 403 significa que no tienes permiso para ese recurso, 429 significa que hiciste demasiadas peticiones en poco tiempo.
El cierre del círculo de Andrea
Andrea, aquella desarrolladora de Guadalajara, pasó por exactamente este proceso. Su líder técnico le compartió la documentación de la API de rastreo, que requería un token Bearer. Ella abrió Postman, pegó el endpoint, agregó el encabezado de autorización, hizo clic en Send y vio aparecer el estatus del envío en segundos.
El código JSON que devolvió la API mostraba que el paquete estaba en tránsito en Monterrey, con una estimación de entrega para el día siguiente. Toda esa información, disponible con una sola petición. Lo que llevaba dos semanas siendo teoría, en cinco minutos se convirtió en algo real y tangible.
Esa es exactamente la experiencia que queremos que tengas tú. Antes de escribir cualquier código de integración, habla primero con la API usando Postman o curl. Entiende cómo responde. Experimenta con los parámetros. Lee los errores. Cuando llegues al código, ya sabrás exactamente qué esperar.