En los inicios de la informática, los programas de ordenador eran islas solitarias. Si querías que tu software tuviera un mapa, tenías que programar el mapa tú mismo; si querías procesar un pago, debías construir un sistema bancario desde cero. Hoy en día, el desarrollo moderno se basa en la colaboración mediante piezas interconectadas. Tu aplicación no necesita saber cómo predecir el clima o cómo validar una tarjeta de crédito, simplemente necesita saber cómo pedírselo a quien ya lo hace perfectamente.
El puente que permite esta comunicación entre tu código y los servidores de gigantes como Google, Stripe o WhatsApp se llama API (Interfaz de Programación de Aplicaciones).
En este artículo, desmitificaremos qué es exactamente una API RESTful, aprenderemos a leer la documentación de servicios externos y utilizaremos la librería más elegante de Python para extraer y enviar datos por la red como un desarrollador profesional.
¿Qué es una API RESTful? (La analogía del restaurante)
Para entender una API, la analogía más famosa (y exacta) es la de un restaurante. Tú (el cliente) estás sentado en la mesa y sabes lo que quieres comer. La cocina (el servidor y la base de datos) tiene la comida y sabe cómo prepararla. Sin embargo, no puedes entrar directamente a la cocina a coger los ingredientes. Necesitas un camarero.
La API es ese camarero. Tú le entregas tu petición (una orden estructurada), el camarero la lleva a la cocina y te devuelve exactamente lo que pediste en un formato que puedes consumir.
El término RESTful simplemente indica que este «camarero» sigue un conjunto de reglas universales basadas en el protocolo HTTP de internet. Se comunica utilizando un lenguaje estándar, casi siempre en formato JSON (un formato de texto estructurado mediante diccionarios y listas que Python entiende nativamente).
Los 4 Verbos HTTP Fundamentales
Cuando te comunicas con una API REST, debes indicarle qué intención tienes utilizando un «verbo» o método:
- GET (Leer): Pides información. (Ej. «Dame los datos del usuario 5»).
- POST (Crear): Envías información nueva. (Ej. «Crea este nuevo cliente en la base de datos»).
- PUT / PATCH (Actualizar): Modificas información existente. (Ej. «Cambia la dirección del cliente 5»).
- DELETE (Borrar): Eliminas un registro. (Ej. «Borra al cliente 5»).
La Herramienta de Trabajo: La Librería requests
Aunque Python trae una librería nativa para conexiones de red (urllib), su sintaxis es compleja y pesada. La industria entera utiliza una librería de terceros llamada requests, famosa por su lema: «HTTP for Humans» (HTTP para humanos).
Para instalarla, abre tu terminal y ejecuta:
Bash
pip install requests
Ejemplo 1: Petición GET (Extrayendo datos)
Vamos a consumir una API pública y gratuita (JSONPlaceholder) que simula una base de datos de usuarios. Nuestro objetivo es obtener los datos de un usuario específico y extraer su nombre y correo.
Python
import requests
# 1. Definimos el endpoint (la URL del camarero)
url = "https://jsonplaceholder.typicode.com/users/1"
try:
# 2. Hacemos la petición GET
respuesta = requests.get(url)
# 3. Verificamos que todo salió bien (Código 200 OK)
respuesta.raise_for_status()
# 4. Transformamos la respuesta de texto plano a un diccionario de Python
datos_usuario = respuesta.json()
# 5. Manipulamos los datos
print("=== Datos del Usuario ===")
print(f"Nombre: {datos_usuario['name']}")
print(f"Email: {datos_usuario['email']}")
print(f"Ciudad: {datos_usuario['address']['city']}")
except requests.exceptions.RequestException as e:
print(f"Error de conexión: {e}")
Ejemplo 2: Petición POST (Enviando datos)
Ahora imaginemos que quieres crear un nuevo registro. Para ello, usamos el método POST y le enviamos la información estructurada en un diccionario (payload).
Python
import requests
url = "https://jsonplaceholder.typicode.com/posts"
# Los datos que queremos guardar en el servidor externo
nuevo_articulo = {
"title": "Aprender APIs con Python",
"body": "Es más fácil de lo que parece.",
"userId": 1
}
# Hacemos la petición POST enviando el diccionario en el parámetro 'json'
respuesta = requests.post(url, json=nuevo_articulo)
if respuesta.status_code == 201: # 201 significa "Created" (Creado con éxito)
print("Artículo guardado correctamente en el servidor.")
print("ID asignado por el servidor:", respuesta.json()['id'])
else:
print("Fallo al guardar. Código:", respuesta.status_code)
Seguridad: Autenticación y API Keys
Los ejemplos anteriores usan APIs públicas. Sin embargo, si quieres conectarte a la API de OpenAI para usar ChatGPT, o a la de Stripe para procesar un pago, no puedes entrar libremente. Las empresas necesitan saber quién eres y, sobre todo, a quién cobrarle.
Para esto se utilizan las API Keys (Claves de API) o Tokens Bearer. Son largas cadenas de texto criptográficas que funcionan como tu carné de identidad. Nunca debes ponerlas directamente en la URL, sino ocultas en las «cabeceras» (Headers) de tu petición.
Python
import requests
import os
from dotenv import load_dotenv
# Cargamos nuestra clave secreta desde el archivo .env
load_dotenv()
MI_API_KEY = os.getenv('OPENWEATHER_API_KEY')
url = "https://api.empresa-privada.com/v1/datos"
# Inyectamos el Token de seguridad en las cabeceras HTTP
cabeceras = {
"Authorization": f"Bearer {MI_API_KEY}",
"Content-Type": "application/json"
}
respuesta = requests.get(url, headers=cabeceras)
Regla de oro: Al igual que vimos en la automatización de correos, NUNCA escribas tu API Key directamente en el código de tu script. Si lo subes a un repositorio público como GitHub por error, bots maliciosos robarán tu clave en segundos y podrían generar cargos de miles de euros en tu tarjeta de crédito vinculada. Usa siempre variables de entorno (.env).
Comprendiendo los Códigos de Estado (Status Codes)
Cuando haces una petición, el servidor siempre te responde con un código numérico. Como profesional, debes conocer las familias de códigos para depurar tu aplicación:
- 2xx (Éxito): Todo ha ido bien.
200 OK(Petición exitosa),201 Created(Registro creado). - 4xx (Error del Cliente): Te has equivocado tú.
400 Bad Request(Faltan datos),401 Unauthorized(Tu API Key es inválida),404 Not Found(La URL no existe). - 5xx (Error del Servidor): El servidor remoto se ha caído o tiene un bug.
500 Internal Server Error,503 Service Unavailable. Aquí tu código está bien, debes esperar a que la empresa repare su sistema.
Conclusión
El consumo de APIs RESTful es el superpoder definitivo en el desarrollo de software. Transforma una aplicación local y aislada en un sistema conectado globalmente. Al dominar la librería requests, los métodos HTTP y el manejo de objetos JSON, adquieres la capacidad de integrar sistemas de Inteligencia Artificial, enviar notificaciones SMS, leer catálogos de e-commerce y procesar pagos con apenas una docena de líneas de código Python.
La próxima vez que tengas un problema complejo en tu arquitectura, antes de intentar programar la solución desde cero, pregúntate: «¿Existirá ya una API para esto?». En la gran mayoría de los casos, la respuesta será sí.
