API REST con Flask

Las API REST representan uno de los paradigmas más utilizados en el desarrollo web moderno para crear servicios que permiten la comunicación entre diferentes aplicaciones. Flask, con su filosofía minimalista y flexible, se ha convertido en una herramienta fundamental para construir estas interfaces de programación de aplicaciones de manera eficiente y escalable.

Fundamentos de las API REST

Una API REST (Representational State Transfer) es un estilo arquitectónico que define un conjunto de restricciones y principios para crear servicios web. Este enfoque se basa en el protocolo HTTP y utiliza sus métodos nativos para realizar operaciones sobre recursos identificados mediante URLs.

Los principios fundamentales de REST incluyen la arquitectura cliente-servidor, la ausencia de estado entre peticiones, la capacidad de almacenamiento en caché y una interfaz uniforme. Estos principios garantizan que las API sean escalables, mantenibles y fáciles de consumir desde diferentes tipos de clientes.

Flask proporciona las herramientas necesarias para implementar estos principios de manera natural. Su decorador de rutas permite mapear URLs a funciones Python, mientras que su sistema de manejo de peticiones HTTP facilita el procesamiento de diferentes métodos como GET, POST, PUT y DELETE.

Métodos HTTP y operaciones CRUD

Las operaciones CRUD (Create, Read, Update, Delete) se mapean directamente con los métodos HTTP en una API REST. Esta correspondencia proporciona una interfaz intuitiva y estándar para manipular recursos.

El método GET se utiliza para recuperar información sin modificar el estado del servidor. En Flask, esto se implementa mediante rutas que devuelven datos en formato JSON:

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/usuarios', methods=['GET'])
def obtener_usuarios():
    usuarios = [
        {'id': 1, 'nombre': 'Ana', 'email': 'ana@email.com'},
        {'id': 2, 'nombre': 'Carlos', 'email': 'carlos@email.com'}
    ]
    return jsonify(usuarios)

El método POST permite crear nuevos recursos. Flask facilita el acceso a los datos enviados en el cuerpo de la petición mediante el objeto request:

from flask import request

@app.route('/usuarios', methods=['POST'])
def crear_usuario():
    datos = request.get_json()
    nuevo_usuario = {
        'id': len(usuarios) + 1,
        'nombre': datos['nombre'],
        'email': datos['email']
    }
    usuarios.append(nuevo_usuario)
    return jsonify(nuevo_usuario), 201

Manejo de rutas dinámicas y parámetros

Las rutas dinámicas permiten capturar valores variables desde la URL, lo que resulta esencial para identificar recursos específicos en una API REST. Flask utiliza una sintaxis intuitiva con corchetes angulares para definir estos parámetros:

@app.route('/usuarios/<int:usuario_id>', methods=['GET'])
def obtener_usuario(usuario_id):
    usuario = next((u for u in usuarios if u['id'] == usuario_id), None)
    if usuario:
        return jsonify(usuario)
    return jsonify({'error': 'Usuario no encontrado'}), 404

Los convertidores de tipo como int, float y string garantizan que los parámetros se procesen correctamente. Esto mejora la robustez de la API al validar automáticamente el formato de los datos de entrada.

Para operaciones más complejas, Flask permite combinar parámetros de ruta con parámetros de consulta. Los parámetros de consulta se acceden mediante request.args:

@app.route('/usuarios', methods=['GET'])
def listar_usuarios():
    limite = request.args.get('limite', 10, type=int)
    pagina = request.args.get('pagina', 1, type=int)
    
    inicio = (pagina - 1) * limite
    fin = inicio + limite
    
    usuarios_paginados = usuarios[inicio:fin]
    return jsonify({
        'usuarios': usuarios_paginados,
        'pagina': pagina,
        'total': len(usuarios)
    })

Códigos de estado HTTP y respuestas

Los códigos de estado HTTP comunican el resultado de cada operación de manera estándar. Flask permite especificar estos códigos junto con las respuestas JSON para proporcionar información clara sobre el resultado de cada petición.

Los códigos de la serie 2xx indican éxito. El código 200 se utiliza para operaciones exitosas, mientras que 201 indica la creación exitosa de un recurso:

@app.route('/usuarios/<int:usuario_id>', methods=['PUT'])
def actualizar_usuario(usuario_id):
    datos = request.get_json()
    usuario = next((u for u in usuarios if u['id'] == usuario_id), None)
    
    if not usuario:
        return jsonify({'error': 'Usuario no encontrado'}), 404
    
    usuario.update(datos)
    return jsonify(usuario), 200

Los códigos de la serie 4xx indican errores del cliente. El manejo adecuado de estos errores mejora significativamente la experiencia del desarrollador que consume la API:

@app.route('/usuarios/<int:usuario_id>', methods=['DELETE'])
def eliminar_usuario(usuario_id):
    global usuarios
    usuario = next((u for u in usuarios if u['id'] == usuario_id), None)
    
    if not usuario:
        return jsonify({'error': 'Usuario no encontrado'}), 404
    
    usuarios = [u for u in usuarios if u['id'] != usuario_id]
    return '', 204  # No Content para eliminación exitosa

Validación de datos y manejo de errores

La validación de datos constituye un aspecto crítico en el desarrollo de API REST. Flask proporciona mecanismos para validar tanto la estructura como el contenido de los datos recibidos:

@app.route('/usuarios', methods=['POST'])
def crear_usuario():
    if not request.is_json:
        return jsonify({'error': 'Content-Type debe ser application/json'}), 400
    
    datos = request.get_json()
    
    # Validación de campos requeridos
    campos_requeridos = ['nombre', 'email']
    for campo in campos_requeridos:
        if campo not in datos:
            return jsonify({'error': f'Campo {campo} es requerido'}), 400
    
    # Validación de formato de email
    if '@' not in datos['email']:
        return jsonify({'error': 'Formato de email inválido'}), 400
    
    nuevo_usuario = {
        'id': len(usuarios) + 1,
        'nombre': datos['nombre'],
        'email': datos['email']
    }
    usuarios.append(nuevo_usuario)
    return jsonify(nuevo_usuario), 201

El manejo centralizado de errores mediante decoradores de Flask permite crear respuestas consistentes para diferentes tipos de excepciones:

@app.errorhandler(404)
def no_encontrado(error):
    return jsonify({'error': 'Recurso no encontrado'}), 404

@app.errorhandler(500)
def error_interno(error):
    return jsonify({'error': 'Error interno del servidor'}), 500

Serialización y formato JSON

La serialización JSON es fundamental en las API REST, ya que JSON se ha establecido como el formato estándar para el intercambio de datos. Flask incluye soporte nativo para JSON mediante la función jsonify, que maneja automáticamente la conversión de estructuras de datos Python:

@app.route('/usuarios/<int:usuario_id>/perfil', methods=['GET'])
def obtener_perfil_usuario(usuario_id):
    usuario = next((u for u in usuarios if u['id'] == usuario_id), None)
    
    if not usuario:
        return jsonify({'error': 'Usuario no encontrado'}), 404
    
    perfil = {
        'usuario': usuario,
        'estadisticas': {
            'fecha_registro': '2024-01-15',
            'ultimo_acceso': '2024-01-20',
            'posts_publicados': 15
        },
        'configuracion': {
            'notificaciones': True,
            'perfil_publico': False
        }
    }
    
    return jsonify(perfil)

Para casos más complejos, Flask permite personalizar la serialización mediante el uso de clases y métodos específicos que transforman objetos Python en representaciones JSON apropiadas para la API.