API REST Flutter #

Un paquete Flutter integral para la gestión de datos con capacidades online y offline, diseñado para aplicaciones empresariales que requieren sincronización robusta de datos y operaciones sin conexión.

Características #

• ✅ Modo Online/Offline: Cambio automático entre operaciones en línea y fuera de línea
• ✅ Sincronización de Datos: Sincronización bidireccional con seguimiento de estado de transferencia
• ✅ Validación Basada en Esquemas: Validación dinámica de datos usando esquemas JSON
• ✅ Operaciones CRUD Completas: Crear, leer, actualizar y eliminar con soporte offline
• ✅ Autenticación Integrada: Sistema de gestión de sesiones tipo OAuth
• ✅ Caché Local: Almacenamiento local usando ObjectBox para acceso rápido
• ✅ Notificaciones Push: Integración con Firebase Push Notifications
• ✅ Validación con Regex: Validación de tipos de datos con expresiones regulares personalizables
• ✅ Paginación: Soporte completo para paginación de resultados
• ✅ Multi-proveedor: Arquitectura basada en proveedores para diferentes fuentes de datos

Instalación #

Añade esta línea a tu archivo pubspec.yaml:

dependencies:
  api_rest_flutter: ^4.0.0

Luego ejecuta:

flutter pub get

Configuración Inicial #

1. Inicialización Básica #

import 'package:api_rest_flutter/api_rest.dart';

void main() async {
  // Obtener instancia singleton
  final apiRest = ApiRest();
  
  // Configurar modo de trabajo
  apiRest.modeToWork = ModeToWork.online; // o ModeToWork.offline
  
  // Inicializar con configuración
  await apiRest.inicializar(
    urlBase: 'https://api.ejemplo.com',
    proyecto: 'mi_proyecto',
    empresa: 'mi_empresa',
  );
  
  runApp(MyApp());
}

2. Configuración de Autenticación #

// Login de usuario
final resultado = await apiRest.login(
  usuario: 'usuario@ejemplo.com',
  password: 'contraseña123',
);

if (resultado['success']) {
  print('Sesión iniciada correctamente');
  final token = resultado['token'];
  // El token se gestiona automáticamente
}

// Verificar estado de sesión
bool sesionActiva = await apiRest.verificarSesion();

Uso #

Operaciones CRUD #

Crear/Guardar Registro

final nuevoRegistro = {
  'nombre': 'Juan Pérez',
  'email': 'juan@ejemplo.com',
  'edad': 30,
  'activo': true,
};

final resultado = await apiRest.guardar(
  tabla: 'usuarios',
  registro: nuevoRegistro,
);

if (resultado['success']) {
  print('Registro guardado con ID: ${resultado['id']}');
}

Leer por ID

final usuario = await apiRest.leeById(
  tabla: 'usuarios',
  id: '123',
);

if (usuario != null) {
  print('Usuario encontrado: ${usuario['nombre']}');
}

Actualizar Registro

final cambios = {
  'id': '123',
  'email': 'nuevo_email@ejemplo.com',
  'actualizado': DateTime.now().toIso8601String(),
};

final resultado = await apiRest.actualizar(
  tabla: 'usuarios',
  registro: cambios,
);

Eliminar Registro

final resultado = await apiRest.eliminar(
  tabla: 'usuarios',
  id: '123',
);

Consultas Avanzadas #

Búsqueda con Filtros

final filtros = {
  'activo': true,
  'edad': {'\$gte': 18, '\$lte': 65},
  'departamento': 'ventas',
};

final resultados = await apiRest.obtener(
  tabla: 'usuarios',
  where: filtros,
  orderBy: {'nombre': 1}, // 1 ascendente, -1 descendente
  limit: 20,
  skip: 0,
);

Paginación

// Obtener página específica
final pagina = await apiRest.obtenerPagina(
  tabla: 'productos',
  pagina: 2,
  registrosPorPagina: 10,
  where: {'categoria': 'electronica'},
);

print('Total registros: ${pagina['total']}');
print('Registros en página: ${pagina['datos'].length}');

Sincronización de Datos #

Sincronización Manual

// Subir cambios locales al servidor
final resultadoSubida = await apiRest.sincronizarSubida(
  tabla: 'pedidos',
);

print('Registros sincronizados: ${resultadoSubida['count']}');

// Descargar cambios del servidor
final resultadoBajada = await apiRest.sincronizarBajada(
  tabla: 'productos',
  ultimaSincronizacion: DateTime.now().subtract(Duration(days: 1)),
);

Sincronización Automática

// Configurar sincronización automática cada 5 minutos
apiRest.configurarSincronizacionAutomatica(
  intervalo: Duration(minutes: 5),
  tablas: ['usuarios', 'pedidos', 'productos'],
);

Validación con Esquemas #

// Definir esquema
final esquemaUsuario = {
  'nombre': {
    'tipo': 'string',
    'requerido': true,
    'minLength': 3,
    'maxLength': 50,
  },
  'email': {
    'tipo': 'email',
    'requerido': true,
    'regex': r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$',
  },
  'edad': {
    'tipo': 'number',
    'min': 0,
    'max': 120,
  },
};

// Validar datos antes de guardar
final datosUsuario = {
  'nombre': 'Ana García',
  'email': 'ana@ejemplo.com',
  'edad': 25,
};

final esValido = apiRest.validarConEsquema(
  datos: datosUsuario,
  esquema: esquemaUsuario,
);

if (esValido) {
  await apiRest.guardar(tabla: 'usuarios', registro: datosUsuario);
}

Modo Offline #

// Cambiar a modo offline
apiRest.modeToWork = ModeToWork.offline;

// Las operaciones ahora trabajan con la base de datos local
final usuariosLocales = await apiRest.obtener(
  tabla: 'usuarios',
  where: {'sincronizado': false},
);

// Los cambios se marcan para sincronización posterior
await apiRest.guardar(
  tabla: 'usuarios',
  registro: {'nombre': 'Usuario Offline'},
);

// Cambiar a modo online y sincronizar
apiRest.modeToWork = ModeToWork.online;
await apiRest.sincronizarTodo();

Utilidades Adicionales #

Clase UtilsDataApiRest #

import 'package:api_rest_flutter/util/utils_data_api_rest.dart';

final utils = UtilsDataApiRest();

// Validación de email
bool emailValido = utils.validarEmail('usuario@ejemplo.com');

// Validación de número de teléfono
bool telefonoValido = utils.validarTelefono('+34 600 123 456');

// Formateo de fechas
String fechaFormateada = utils.formatearFecha(DateTime.now());

// Cálculo de paginación
Map paginacion = utils.calcularPaginacion(
  totalRegistros: 100,
  paginaActual: 3,
  registrosPorPagina: 10,
);

Manejo de Errores #

try {
  final resultado = await apiRest.guardar(
    tabla: 'pedidos',
    registro: datosPedido,
  );
  
  if (resultado['success']) {
    print('Operación exitosa');
  } else {
    print('Error: ${resultado['message']}');
  }
} catch (e) {
  print('Error de conexión: $e');
  
  // Cambiar automáticamente a modo offline
  apiRest.modeToWork = ModeToWork.offline;
  
  // Reintentar operación en modo offline
  await apiRest.guardar(
    tabla: 'pedidos',
    registro: datosPedido,
  );
}

Configuración Avanzada #

Personalización de Proveedores #

// Configurar timeouts personalizados
apiRest.configurarHttpProvider(
  timeout: Duration(seconds: 30),
  reintentos: 3,
);

// Configurar caché local
apiRest.configurarObjectBox(
  directorio: 'mi_cache_personalizado',
  tamañoMaximo: 100 * 1024 * 1024, // 100 MB
);

// Configurar notificaciones push
apiRest.configurarNotificaciones(
  onMessage: (mensaje) {
    print('Nueva notificación: ${mensaje.title}');
  },
  onTokenRefresh: (token) {
    print('Nuevo token FCM: $token');
  },
);

Requisitos #

• Flutter SDK: >=3.1.0
• Dart SDK: >=3.1.0 <4.0.0
• iOS: >=11.0
• Android: minSdkVersion 21

Dependencias Principales #

Este paquete utiliza un ecosistema de proveedores especializados:

• flutter_objectbox_provider: Base de datos local
• flutter_http_provider: Operaciones HTTP
• flutter_security_provider: Seguridad y autenticación
• flutter_firebase_push_notification_provider: Notificaciones push
• flutter_data_cloud_provider: Operaciones en la nube
• flutter_data_mobile_provider: Operaciones móviles
• flutter_data_shp_provider: SharedPreferences
• flutter_utils_providers: Utilidades generales
• flutter_models_provider: Modelos de datos

Contribuir #

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea tu rama de características (git checkout -b feature/NuevaCaracteristica)
3. Commit tus cambios (git commit -m 'Añadir nueva característica')
4. Push a la rama (git push origin feature/NuevaCaracteristica)
5. Abre un Pull Request

Testing #

Ejecuta las pruebas con:

flutter test

Para ejecutar pruebas específicas:

flutter test test/api_rest_test.dart

Licencia #

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Autor #

RobleSistemas

Soporte #

Para reportar problemas o solicitar nuevas características, por favor abre un issue en el repositorio de GitHub.

Changelog #

Ver CHANGELOG.md para el historial de cambios detallado.