Working with JSON APIs: A Beginner's Guide — csv-x.com

Aún recuerdo el día en que accidentalmente hice caer toda la tubería de datos de nuestra empresa. Era 2015, llevaba tres meses en mi primer trabajo como desarrollador junior en una startup de fintech y acababa de enviar un código que realizó 50,000 solicitudes de API en menos de dos minutos. Nuestro límite de solicitudes era de 1,000 por hora. Las llamadas telefónicas de nuestro proveedor de API no fueron agradables, y tampoco lo fue la conversación con mi CTO. Ese momento embarazoso me enseñó más sobre trabajar con API JSON que cualquier tutorial podría, y es por eso que estoy escribiendo esta guía hoy, para que puedas aprender de mis errores en lugar de cometer los tuyos.

Durante los últimos nueve años como ingeniero backend y especialista en integraciones de API, he trabajado con cientos de diferentes API JSON, desde servicios meteorológicos simples hasta proveedores de datos financieros complejos. He construido sistemas que procesan millones de llamadas a API diariamente y he depurado problemas de integración que costaron a las empresas miles de dólares por hora de inactividad. Lo que he aprendido es que trabajar con API JSON no se trata solo de hacer solicitudes HTTP y parsear respuestas. Se trata de entender los límites de tasa, manejar los errores de manera adecuada, gestionar la autenticación de forma segura y construir sistemas resilientes que no se desmoronen cuando las cosas van mal.

Esta guía te llevará a través de todo lo que necesitas saber para trabajar con confianza con las API JSON, ya sea que estés construyendo tu primera integración o buscando mejorar tus habilidades. Cubriremos los fundamentos, exploraremos trampas comunes y profundizaremos en técnicas prácticas que te harán un desarrollador más efectivo.

Entendiendo Lo Que Son Realmente las API JSON

Antes de profundizar en los detalles técnicos, establezcamos de qué estamos hablando realmente. Una API JSON es simplemente una forma en que diferentes aplicaciones de software se comunican entre sí a través de Internet utilizando JSON (Notación de Objetos de JavaScript) como formato de datos. Piénsalo como un camarero en un restaurante: tú (el cliente) haces una solicitud para algo específico, el camarero lleva esa solicitud a la cocina (el servidor) y trae exactamente lo que pediste en un formato estandarizado.

JSON se ha convertido en el formato dominante para las API web porque es ligero, legible por humanos y es compatible con prácticamente todos los lenguajes de programación. Cuando comencé mi carrera, XML aún era común y déjame decirte: trabajar con JSON es infinitamente más agradable. Una respuesta JSON típica podría verse así:

{"user": {"id": 12345, "name": "Sarah Chen", "email": "[email protected]", "created_at": "2024-01-15T10:30:00Z"}}

Compara eso con el equivalente en XML con todas sus etiquetas de apertura y cierre, y entenderás por qué JSON ganó. Es conciso, fácil de leer y se mapea naturalmente a estructuras de datos en la mayoría de los lenguajes de programación: objetos en JavaScript, diccionarios en Python, mapas en Go, y así sucesivamente.

La mayoría de las API JSON modernas siguen los principios REST (Transferencia de Estado Representacional), lo que significa que utilizan métodos HTTP estándar como GET (recuperar datos), POST (crear datos), PUT o PATCH (actualizar datos) y DELETE (eliminar datos). Esta estandarización hace que las API sean predecibles y más fáciles de trabajar. Cuando ves una solicitud GET a /api/users/12345, puedes suponer razonablemente que está obteniendo información sobre el usuario 12345. Un POST a /api/users probablemente esté creando un nuevo usuario.

Entender esta base es crucial porque da forma a cómo interactuarás con prácticamente todas las API que encuentres. Los patrones son consistentes a través de diferentes servicios, lo que significa que una vez que domines los conceptos básicos de una API, puedes aplicar ese conocimiento a cientos de otras.

Haciendo Tu Primera Solicitud de API

Vamos a ser prácticos. La forma más sencilla de interactuar con una API JSON es a través de una herramienta como curl o Postman, pero eventualmente querrás hacer solicitudes desde tu código. Te mostraré ejemplos en Python ya que es ampliamente accesible, pero los conceptos se aplican a cualquier lenguaje.

Aquí está la solicitud de API más básica que puedes hacer:

import requests
response = requests.get('https://api.example.com/users/12345')
data = response.json()
print(data['name'])

Este fragmento de cuatro líneas hace mucho: envía una solicitud HTTP GET a la API, recibe la respuesta, parsea el JSON en un diccionario de Python y extrae un campo específico. Sencillo, ¿verdad? Pero este código tiene al menos cinco problemas graves que harían que fallara en producción.

Primero, no hay manejo de errores. ¿Qué pasa si la red está caída? ¿Qué sucede si el usuario no existe y la API devuelve un 404? ¿Qué pasa si la API no está disponible temporalmente y devuelve un 503? Tu código se caerá. En segundo lugar, no hay un tiempo de espera especificado. Si el servidor de la API se cuelga, tu código esperará indefinidamente. En tercer lugar, no hay autenticación: la mayoría de las API reales requieren algún tipo de credenciales. Cuarto, no hay consideración por la limitación de tasa. Y quinto, no hay validación de que la respuesta realmente contenga los datos que esperas.

Aquí tienes una versión más robusta que aborda estos problemas:

import requests
from requests.exceptions import RequestException
import time

def fetch_user(user_id, api_key, max_retries=3):
    url = f'https://api.example.com/users/{user_id}'
    headers = {'Authorization': f'Bearer {api_key}'}
    
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, timeout=10)
            response.raise_for_status()
            data = response.json()
            
            if 'name' not in data:
                raise ValueError('Invalid response format')
            
            return data
        
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 attempt)
    
    return None