Tutorial Flask: Parámetros y query strings

request.args para query strings

Los query strings son parámetros que se envían a través de la URL después del símbolo ?, permitiendo que los clientes pasen información adicional a nuestros endpoints. En Flask, el objeto request.args nos proporciona acceso directo a estos parámetros de manera sencilla y eficiente.

Acceso básico a query strings

Flask almacena todos los parámetros de consulta en request.args, que funciona como un diccionario especial llamado ImmutableMultiDict. Para acceder a estos parámetros, primero debemos importar el objeto request:

from flask import Flask, request

app = Flask(__name__)

@app.route('/productos')
def obtener_productos():
    categoria = request.args.get('categoria')
    return f"Productos de la categoría: {categoria}"

Con esta ruta, una petición a /productos?categoria=electronica devolvería "Productos de la categoría: electronica".

Métodos de acceso a parámetros

El objeto request.args ofrece varios métodos para recuperar parámetros según nuestras necesidades:

Método get() con valores por defecto:

@app.route('/buscar')
def buscar_productos():
    termino = request.args.get('q', 'todos')
    limite = request.args.get('limite', '10')
    
    return {
        'termino_busqueda': termino,
        'limite_resultados': limite
    }

Acceso directo con corchetes:

@app.route('/usuario')
def obtener_usuario():
    try:
        user_id = request.args['id']
        return f"Usuario ID: {user_id}"
    except KeyError:
        return "ID de usuario requerido", 400

Conversión de tipos de datos

Los query strings siempre llegan como cadenas de texto, pero Flask nos permite convertirlos fácilmente a otros tipos usando el parámetro type:

@app.route('/paginar')
def paginar_resultados():
    pagina = request.args.get('pagina', 1, type=int)
    por_pagina = request.args.get('por_pagina', 20, type=int)
    
    inicio = (pagina - 1) * por_pagina
    fin = inicio + por_pagina
    
    return {
        'pagina_actual': pagina,
        'elementos_por_pagina': por_pagina,
        'rango': f"{inicio}-{fin}"
    }

Conversión a tipos booleanos:

@app.route('/articulos')
def listar_articulos():
    incluir_archivados = request.args.get('archivados', False, type=bool)
    ordenar_desc = request.args.get('desc', False, type=bool)
    
    return {
        'incluye_archivados': incluir_archivados,
        'orden_descendente': ordenar_desc
    }

Manejo de múltiples valores

Algunos parámetros pueden aparecer múltiples veces en la URL. Flask maneja esto automáticamente:

@app.route('/filtrar')
def filtrar_productos():
    # URL: /filtrar?tag=oferta&tag=nuevo&tag=destacado
    tags = request.args.getlist('tag')
    colores = request.args.getlist('color')
    
    return {
        'tags_seleccionados': tags,
        'colores_disponibles': colores,
        'total_filtros': len(tags) + len(colores)
    }

Ejemplo práctico con datos en memoria

Veamos un ejemplo completo que simula una API de productos usando datos almacenados en memoria:

from flask import Flask, request, jsonify

app = Flask(__name__)

# Datos de ejemplo en memoria
productos = [
    {'id': 1, 'nombre': 'Laptop Gaming', 'categoria': 'electronica', 'precio': 1200, 'stock': 5},
    {'id': 2, 'nombre': 'Mouse Inalámbrico', 'categoria': 'electronica', 'precio': 25, 'stock': 50},
    {'id': 3, 'nombre': 'Escritorio Madera', 'categoria': 'muebles', 'precio': 300, 'stock': 8},
    {'id': 4, 'nombre': 'Silla Ergonómica', 'categoria': 'muebles', 'precio': 150, 'stock': 12}
]

@app.route('/api/productos')
def obtener_productos():
    # Parámetros de filtrado
    categoria = request.args.get('categoria')
    precio_min = request.args.get('precio_min', type=int)
    precio_max = request.args.get('precio_max', type=int)
    
    # Parámetros de paginación
    pagina = request.args.get('pagina', 1, type=int)
    limite = request.args.get('limite', 10, type=int)
    
    # Filtrar productos
    productos_filtrados = productos.copy()
    
    if categoria:
        productos_filtrados = [p for p in productos_filtrados if p['categoria'] == categoria]
    
    if precio_min:
        productos_filtrados = [p for p in productos_filtrados if p['precio'] >= precio_min]
    
    if precio_max:
        productos_filtrados = [p for p in productos_filtrados if p['precio'] <= precio_max]
    
    # Aplicar paginación
    inicio = (pagina - 1) * limite
    fin = inicio + limite
    productos_paginados = productos_filtrados[inicio:fin]
    
    return jsonify({
        'productos': productos_paginados,
        'total': len(productos_filtrados),
        'pagina': pagina,
        'limite': limite,
        'filtros_aplicados': {
            'categoria': categoria,
            'precio_min': precio_min,
            'precio_max': precio_max
        }
    })

Verificación de parámetros existentes

Para comprobar si un parámetro específico está presente en la URL, podemos usar el operador in:

@app.route('/configuracion')
def obtener_configuracion():
    config = {'modo': 'basico'}
    
    if 'debug' in request.args:
        config['debug'] = request.args.get('debug', type=bool)
    
    if 'formato' in request.args:
        formato = request.args.get('formato')
        if formato in ['json', 'xml', 'csv']:
            config['formato_salida'] = formato
    
    return config

Esta aproximación nos permite crear endpoints flexibles que respondan de manera diferente según los parámetros proporcionados, manteniendo la funcionalidad básica cuando no se especifican parámetros adicionales.