Cómo integrar APIs con bases de datos corporativas

Introducción

Conectar una API con una base de datos corporativa exige algo más que abrir una conexión y ejecutar una consulta. Hay que definir el acceso permitido, proteger el modelo de información, garantizar la seguridad y mantener la consistencia de los datos cuando se producen errores, cambios o accesos simultáneos.

Imagina que una empresa conserva sus clientes, contratos e incidencias en una base de datos y necesita consultar esa información desde una aplicación web, un sistema de asistencia técnica o una herramienta móvil. Es posible construir una API que ofrezca únicamente las operaciones necesarias, sin entregar credenciales de la base de datos a cada aplicación ni permitir que los consumidores conozcan sus tablas internas.

El reto consiste en convertir los registros de una base de datos en operaciones empresariales bien definidas: consultar un cliente autorizado, registrar una incidencia sin duplicarla, conocer el estado de un pedido o recuperar cambios desde la última sincronización. En esta guía veremos cómo diseñar ese recorrido, qué decisiones tomar antes de programar y cómo comprobar que la integración es útil y mantenible.

Índice

• Qué significa integrar una API y una base de datos corporativa
• Arquitectura recomendada y responsabilidades
• Definir el contrato de datos antes de programar
• Preparar la base de datos para la integración
• Publicar consultas mediante una API: ejemplo práctico
• Gestionar escrituras, transacciones y duplicados
• Guardar en una base de datos información procedente de otras APIs
• Seguridad y control de acceso de extremo a extremo
• Errores, consistencia y recuperación
• Rendimiento y crecimiento de la integración
• Pruebas y puesta en producción
• Caso práctico: una empresa de servicios técnicos
• Errores habituales y cómo evitarlos
• Preguntas frecuentes
• Conclusión

Qué significa integrar una API y una base de datos corporativa

Una base de datos almacena y organiza información; una API define qué operaciones pueden solicitar otras aplicaciones y con qué condiciones. Ambas piezas resuelven problemas distintos. La base de datos puede contener cientos de tablas, índices y relaciones, mientras que una API debería publicar un conjunto reducido de recursos y acciones comprensibles para quien la utiliza.

Por ejemplo, una tabla puede contener información técnica sobre clientes, pero el consumidor de la API quizá solo necesite su identificador, nombre comercial y estado. No debería recibir direcciones privadas, notas internas ni campos de facturación porque existan en la misma tabla.

Cuatro recorridos que conviene distinguir

• Aplicación → API propia → base de datos: una aplicación consulta o modifica información corporativa a través de un servicio controlado.
• Base de datos → servicio → API externa: un proceso toma información autorizada del sistema interno y la transmite a otro sistema.
• API externa → proceso de integración → base de datos: un conector recibe o descarga información y la almacena localmente después de validarla.
• Eventos o cambios → proceso de integración → base de datos: los cambios se procesan de manera asíncrona cuando no es necesario actualizar todos los sistemas en el mismo instante.

La diferencia importa porque cada recorrido plantea problemas específicos. Publicar una consulta necesita controles de lectura y exposición; registrar un pedido exige transacciones y prevención de duplicados; importar cambios periódicos requiere puntos de control y mecanismos de reanudación.

Este artículo se centra en cómo unir una capa API con su almacenamiento. Si la necesidad principal es coordinar varias bases de datos entre sí, conviene estudiar también cómo integrar varias bases de datos dentro de una empresa. No son exactamente el mismo problema.

Arquitectura recomendada: separar consumidores, operaciones y almacenamiento

Para una microempresa o un departamento con recursos limitados no es necesario desplegar una plataforma de microservicios. Una API pequeña, bien organizada y documentada puede ser suficiente. Lo importante es separar responsabilidades, aunque inicialmente todas residan en una misma aplicación.

1. Consumidor: aplicación web, herramienta móvil, automatización o sistema asociado que realiza una petición.
2. Capa de entrada: HTTPS, autenticación, autorización, limitación de peticiones y validación del formato recibido.
3. Servicio de aplicación: interpreta la operación solicitada y aplica las reglas de negocio.
4. Capa de acceso a datos: ejecuta consultas parametrizadas, controla transacciones y utiliza conexiones gestionadas.
5. Base de datos corporativa: almacena los registros, impone restricciones de integridad y mantiene la información persistente.

El consumidor solicita «consultar el cliente 418», no «ejecutar esta sentencia SQL». La API comprueba si la identidad tiene permiso, decide qué campos pueden mostrarse y utiliza la base de datos para obtenerlos. Una estructura así permite modificar índices, vistas o tablas sin obligar a cambiar todos los clientes de la API.

Por qué no conviene exponer directamente el motor de base de datos

Entregar a aplicaciones externas un usuario y una contraseña de PostgreSQL, MariaDB o SQL Server multiplica la superficie de ataque. Además, obliga a distribuir secretos, dificulta controlar las operaciones permitidas y acopla el software consumidor al esquema interno. Una API no elimina todos esos riesgos, pero permite establecer una frontera de control más clara.

Incluso en una red privada conviene evitar que una aplicación de presentación tenga permisos administrativos. La recomendación es acceso a través de un servicio definido y credenciales de base de datos con privilegios mínimos. Para profundizar en la separación de identidades, roles y permisos puede consultarse cómo organizar usuarios y permisos en una base de datos.

La API como contrato estable

Una tabla puede cambiar de nombre o dividirse en dos; la operación empresarial «obtener estado de cliente» puede permanecer igual. Esa independencia no aparece automáticamente: hay que diseñar el contrato y asumir el coste de mantenerlo. Evita presentar las columnas como si fueran recursos públicos inmutables y separa los identificadores internos de los valores que expones a terceros cuando corresponda.

Definir el contrato de datos antes de programar

El primer documento de trabajo no debería ser una colección de consultas SQL, sino una relación de operaciones que necesita el negocio. Para cada operación es útil dejar por escrito quién puede solicitarla, qué información devuelve, cuáles son sus restricciones y qué significa que haya terminado correctamente.

Ejemplo de contrato para una consulta de clientes

Supongamos una API interna destinada a una aplicación de asistencia técnica. Una operación posible sería:

• Recurso: cliente.
• Método y ruta: GET /api/v1/clientes/418.
• Identidad autorizada: personal o servicio técnico con permiso de consulta sobre la organización a la que pertenece el cliente.
• Respuesta: identificador, nombre comercial, estado y fecha de última actualización.
• Campos excluidos: datos bancarios, notas privadas y cualquier otro atributo ajeno a la necesidad del consumidor.
• Situaciones especiales: cliente inexistente, cliente fuera del ámbito autorizado y base de datos temporalmente indisponible.

Una respuesta ilustrativa puede tener este aspecto:

{
  "id": 418,
  "nombre_comercial": "Taller Norte",
  "estado": "activo",
  "actualizado_en": "2026-10-20T09:30:00Z"
}

El nombre de los campos, el formato de fecha y los posibles valores de estado deben ser decisiones expresas. Si «activo» significa que puede recibir servicio, no debe reutilizarse ese campo para expresar que la cuenta está al corriente de pago. Una API fiable evita esas ambigüedades antes de que se propaguen a otras aplicaciones.

Decidir qué se expone y qué permanece interno

Las respuestas deberían construirse con listas explícitas de campos, no copiando indiscriminadamente todos los atributos que devuelve el motor de base de datos. También conviene definir el tratamiento de valores nulos, las unidades, las zonas horarias y el significado de cada identificador. Una misma palabra puede representar entidades distintas en dos departamentos.

Para operaciones que devuelven colecciones hay que acordar filtros permitidos, orden estable, límite de resultados y forma de paginar. Para las escrituras deben concretarse las validaciones, las reglas de autorización, los códigos de respuesta y cómo se identifican intentos repetidos.

La documentación de origen ayuda a distinguir datos técnicos y conceptos de negocio. Es un trabajo complementario al explicado en cómo documentar una base de datos para facilitar su mantenimiento.

Preparar la base de datos para una integración controlada

La calidad de la API está condicionada por la calidad de los datos que consulta o modifica. Antes de desarrollar rutas y controladores hay que revisar identificadores, restricciones, privilegios y las consultas previstas.

Identificadores, integridad y reglas compartidas

Cada entidad debería tener una identidad estable. El nombre comercial de un cliente, su correo electrónico o su teléfono pueden cambiar y no sustituyen a una clave primaria. Cuando la API se conecta con otro sistema, conviene conservar tanto el identificador interno como el identificador externo y documentar su correspondencia.

También deben estar claras las restricciones de unicidad, las relaciones entre entidades y los estados permitidos. Si una incidencia no puede existir sin cliente, esa regla debe formar parte del diseño; si no pueden existir dos operaciones con la misma referencia empresarial, la protección debe contemplar también una restricción en el almacenamiento.

Una vista para separar campos publicados y columnas internas

En una base de datos relacional puede resultar útil ofrecer una vista de lectura con los campos que la API necesita. Este ejemplo usa sintaxis SQL ilustrativa compatible con PostgreSQL y muestra el concepto, no una configuración completa de permisos:

CREATE VIEW api_clientes AS
SELECT
    id,
    organizacion_id,
    nombre_comercial,
    estado,
    actualizado_en
FROM clientes;

La vista reduce el acoplamiento a columnas internas y puede facilitar la revisión de lo que se publica. No sustituye a la autorización: el servicio debe seguir comprobando qué registros puede consultar cada identidad. Las características de seguridad y permisos efectivos de las vistas dependen del motor y de su configuración.

Identidades técnicas distintas según su función

Un servicio que solo consulta clientes no necesita permisos para borrar clientes, crear tablas ni modificar usuarios del motor. Una integración que registra incidencias puede requerir escritura sobre un conjunto concreto de objetos, pero no sobre toda la base. Es conveniente separar las credenciales de lectura, escritura, administración y despliegue, y revisar su alcance real.

Antes de publicar una ruta comprueba asimismo que los índices existentes permiten resolver las consultas habituales. Un filtro repetido por organizacion_id y id debe estudiarse con datos y planes de ejecución reales: añadir índices indiscriminadamente también tiene costes en escritura y mantenimiento.

Publicar consultas mediante una API: ejemplo práctico

Un primer objetivo razonable consiste en crear una consulta de solo lectura. Resulta más sencillo verificar la cadena completa sin asumir todavía los riesgos de las modificaciones.

Paso 1. Obtener la identidad y su ámbito autorizado

La API debe autenticar al solicitante y obtener desde una fuente de confianza la organización o conjunto de clientes a los que puede acceder. Ese ámbito no puede confiarse a un valor que el propio solicitante envíe sin comprobarlo. Si el usuario indica una organización distinta en la URL, la autorización debe impedir que consulte sus datos.

Paso 2. Ejecutar una consulta parametrizada

El servicio traduce la operación en una consulta delimitada. Este fragmento de Python, con la interfaz de psycopg para PostgreSQL, representa únicamente la función de lectura; presupone que la autenticación, la autorización y la obtención de una conexión gestionada ya se han resuelto fuera de ella:

def consultar_cliente(conn, cliente_id, organizacion_id):
    with conn.cursor() as cursor:
        cursor.execute(
            """
            SELECT id, nombre_comercial, estado, actualizado_en
            FROM api_clientes
            WHERE id = %s AND organizacion_id = %s
            """,
            (cliente_id, organizacion_id),
        )
        return cursor.fetchone()

Los parámetros se envían separados de la sentencia SQL. No se construye una cadena interpolando valores recibidos de la petición, lo que ayuda a prevenir la inyección SQL. La consulta limita explícitamente los campos y filtra el identificador por el ámbito autorizado. El resultado todavía debe transformarse en una respuesta JSON, gestionar el caso sin coincidencias y aplicar los controles de acceso del endpoint.

El ejemplo es didáctico, no un servicio listo para abrir a Internet. En producción hacen falta, entre otras piezas, autenticación, validación de entradas, conexiones con límites, tratamiento de errores, configuración segura y supervisión.

Paso 3. Traducir resultados y errores

Si el cliente existe y está autorizado, la API devuelve los campos acordados. Si no existe o el consumidor no debe conocer su existencia, puede devolver 404 Not Found de forma coherente con su política de exposición. Si el motor no responde, lo adecuado es informar de un fallo temporal controlado, no devolver un documento vacío como si no hubiera clientes.

La API no debe enviar al cliente mensajes internos con sentencias SQL, rutas del servidor, credenciales o trazas completas. Esos detalles, debidamente depurados, pertenecen a la observabilidad interna.

Paso 4. Consultar listas sin descargar una tabla completa

Una ruta de colección como GET /api/v1/clientes?limite=50 debe tener un límite máximo del lado del servidor y un orden estable. Cuando el volumen crece, la paginación por cursor puede evitar los problemas de rendimiento y cambios de posición que aparecen al recorrer grandes conjuntos con desplazamientos elevados. El cursor debe representar un punto de continuación válido y no funcionar como autorización.

No todas las consultas necesitan tiempo real. Si la aplicación muestra un directorio que cambia poco, una caché con caducidad apropiada puede reducir la carga. Si muestra un estado operativo crítico, hay que valorar la frescura exigida antes de almacenar resultados en caché.

Gestionar escrituras: validar, confirmar y evitar duplicados

Crear o modificar registros cambia las responsabilidades del servicio. Una lectura fallida suele poder repetirse; una escritura repetida podría generar una segunda incidencia, un segundo pedido o una modificación no deseada. Por eso las rutas de escritura necesitan decisiones explícitas sobre transacciones, concurrencia e idempotencia.

Validar la operación en la capa adecuada

El servicio debe comprobar el formato del mensaje, los permisos del solicitante y las reglas de negocio. La base de datos, por su parte, debe conservar restricciones fundamentales como claves foráneas, unicidad y condiciones de integridad. No conviene confiar en que todos los consumidores validarán correctamente.

En una API de incidencias, por ejemplo, registrar una nueva incidencia implica comprobar que el cliente pertenece al ámbito permitido, que la categoría es válida y que los campos obligatorios están presentes. Solo entonces se ejecuta la operación de persistencia.

Usar transacciones para cambios que deben confirmarse juntos

Si una operación crea una incidencia y registra su primera anotación, ambas escrituras pueden necesitar una única transacción. Si falla una, la otra no debería quedar confirmada de manera aislada. Cuando una operación también invoca una API externa, la transacción de la base de datos no puede garantizar por sí sola que ambos sistemas confirmen simultáneamente el mismo resultado.

En esos casos puede emplearse un patrón de salida transaccional (transactional outbox): la operación guarda en la misma transacción local el cambio empresarial y un evento pendiente de envío. Un proceso posterior transmite el evento, registra su progreso y admite reintentos. Esto reduce el riesgo de confirmar un dato local y perder silenciosamente la notificación externa, aunque sigue siendo necesario controlar duplicados en el destino.

Diseñar idempotencia para peticiones repetidas

Supongamos que un cliente envía POST /api/v1/incidencias, la base de datos confirma la creación y la conexión se corta antes de que la respuesta llegue. El cliente ignora si la incidencia existe. Repetir la petición sin protección podría duplicarla.

Una estrategia es aceptar una clave de idempotencia por operación, asociada al solicitante, a la ruta y al contenido relevante. La primera ejecución conserva la clave y el resultado en el almacenamiento transaccional; una repetición compatible obtiene ese resultado en lugar de producir un segundo efecto. Las claves reutilizadas con contenido diferente deben tratarse de forma explícita.

• Primera petición válida: crea la incidencia y devuelve su identificador.
• Reintento de la misma operación: devuelve o permite recuperar el resultado previamente confirmado.
• Misma clave con otra operación: se rechaza según el contrato definido.
• Fallo previo a la confirmación: permite un reintento seguro después de comprobar el estado registrado.

Evitar que una actualización sobrescriba cambios recientes

Cuando dos personas modifican el mismo registro, una actualización que envía el objeto completo puede borrar cambios de la otra. Un campo de versión o una fecha de modificación, combinado con una condición de actualización verificable, permite aplicar control de concurrencia optimista. Si la versión cambió, la API comunica el conflicto y solicita revisar los datos en lugar de sobrescribirlos sin avisar.

Es preferible publicar acciones con significado —por ejemplo, «cerrar incidencia»— cuando una transición tiene reglas propias, en vez de permitir escribir arbitrariamente cualquier campo de estado.

Guardar en una base de datos información procedente de otras APIs

El sentido del intercambio también puede ser el contrario: la empresa consume una API de un proveedor y necesita almacenar sus resultados en una base de datos propia. El error habitual consiste en construir un script que descarga todo, lo inserta y da por terminada la tarea sin considerar actualizaciones, bajas ni interrupciones.

Descarga inicial e importaciones incrementales

La primera ejecución puede importar un conjunto completo y validarlo. Las siguientes deberían recuperar, cuando el proveedor lo permita, únicamente los cambios desde un punto conocido. Ese punto puede ser un cursor de paginación de cambios, un identificador secuencial o una marca temporal con reglas documentadas. No debe suponerse que todos esos mecanismos ofrecen las mismas garantías.

1. Consultar la API externa utilizando las credenciales autorizadas.
2. Validar estructura, tipos, identidad de origen y campos obligatorios.
3. Transformar los datos al modelo interno sin perder identificadores externos.
4. Insertar o actualizar según una regla comprobable, evitando duplicados.
5. Confirmar el lote en la base de datos.
6. Guardar el punto de avance solo después de confirmar los datos que representa.

Si el proceso se interrumpe tras guardar los datos pero antes de actualizar el cursor, es posible que repita parte del lote. Por eso la importación debe tolerar repeticiones, normalmente mediante claves únicas de origen y operaciones de actualización definidas. No conviene prometer «exactamente una ejecución» cuando el recorrido incluye redes y sistemas distintos.

No olvidar eliminaciones y modificaciones tardías

Una sincronización que solo crea o actualiza registros conservará indefinidamente elementos que desaparecieron del origen. La API externa debe ofrecer, si el caso lo exige, bajas explícitas, estados de archivado o alguna vía fiable para reconciliar un inventario completo. Tampoco basta siempre con consultar por una fecha de modificación: hay que conocer su precisión, orden, zona horaria y tratamiento de cambios retrasados.

Cuando el sistema externo es un ERP o un CRM, el problema incorpora reglas particulares de clientes, productos y pedidos. Para ese recorrido existe un tratamiento específico en cómo integrar APIs con sistemas ERP y CRM.

Qué conservar del proveedor

Es recomendable almacenar el identificador externo, origen, versión o marca de actualización y fecha de importación. No es necesario conservar indiscriminadamente la respuesta JSON íntegra: puede contener información innecesaria o sensible. Si hay una razón operativa para guardar un mensaje original, deben definirse acceso, protección y retención.

Seguridad: proteger la API y también la conexión con la base de datos

La seguridad debe aplicarse en varias capas. Proteger únicamente el punto de entrada HTTPS no evita que una cuenta del motor tenga permisos excesivos o que una ruta devuelva datos de clientes ajenos.

Autenticar no equivale a autorizar

La autenticación identifica al consumidor; la autorización decide qué operación puede realizar y sobre qué registro concreto. Un usuario autenticado puede consultar sus incidencias, pero no por ello debería poder leer las de otra organización cambiando un número en la URL. Este riesgo debe verificarse en todas las consultas y escrituras, no solamente al iniciar sesión.

Según el escenario pueden emplearse sesiones protegidas, OAuth 2.0 con tokens validados o identidades técnicas de servicio. La elección depende de quién consume la API, de cómo se gestionan sus credenciales y de la infraestructura disponible. La simple posesión de un token no debe suplir la comprobación de permisos y ámbito.

Proteger secretos y comunicaciones

• Usar conexiones cifradas donde corresponda, incluidas las comunicaciones entre servicio y base de datos si atraviesan redes o límites de confianza.
• No incorporar contraseñas, cadenas de conexión completas ni tokens en código fuente, repositorios o registros de errores.
• Restringir el acceso de red al motor: solo deberían poder conectarse los componentes que realmente lo necesitan.
• Rotar credenciales con procedimientos que no interrumpan innecesariamente el servicio.
• Separar las identidades y los secretos de desarrollo, pruebas y producción.

Reducir la información expuesta

La API no debe utilizar un SELECT * y entregar toda la fila porque resulte cómodo. Debe seleccionar únicamente lo necesario para cada operación, controlar los atributos modificables y evitar que los mensajes de error revelen detalles internos. Los registros de auditoría tampoco necesitan almacenar cuerpos completos de peticiones con datos personales.

Si varias aplicaciones comparten información, esta revisión es parte de una política más amplia de intercambio seguro, relacionada con cómo compartir datos entre aplicaciones de forma segura.

Errores, consistencia y recuperación ante interrupciones

Una integración puede funcionar correctamente durante semanas y fallar cuando se agota el grupo de conexiones, aparece un bloqueo, cambia un esquema o se interrumpe la red. Diseñar solo el recorrido ideal deja fuera una parte esencial del trabajo.

Distinguir el tipo de fallo

• Petición inválida: faltan campos, un tipo es incorrecto o el formato no cumple el contrato; habitualmente corresponde una respuesta 400 o 422, según el diseño de la API.
• No autenticado o no autorizado: se aplica respectivamente 401 o 403 cuando corresponde, teniendo en cuenta la política de no revelar recursos.
• Recurso inexistente: puede responderse 404.
• Conflicto de estado o de versión: se usa 409 o una respuesta de precondición como 412 cuando el contrato utiliza encabezados condicionales.
• Límite de solicitudes: 429 indica que el consumidor debe moderar su ritmo, preferiblemente con información para reintentar.
• Dependencia temporalmente indisponible: el servicio puede devolver 503, sin fingir un resultado válido.

La API debe diferenciar un error visible para el consumidor del diagnóstico interno. Un identificador de correlación permite relacionar la respuesta con los registros del servicio, sin incluir consultas completas ni datos privados en la respuesta pública.

Reintentos con criterio

No todas las operaciones admiten reintentos automáticos. Las lecturas suelen poder repetirse con límites; las escrituras requieren idempotencia o una comprobación explícita de su resultado. En cualquier caso es importante limitar el número de intentos, aplicar espera progresiva cuando corresponda y evitar que muchos clientes repitan al mismo tiempo una petición que está saturando el sistema.

Un tiempo de espera agotado significa que no se conoce el resultado desde el punto de vista del solicitante; no demuestra que la transacción haya sido revertida. Esta distinción es imprescindible en operaciones que generan efectos empresariales.

Consistencia inmediata o eventual

Si una API escribe en la base de datos transaccional y consulta a continuación esa misma fuente, es posible diseñar una lectura con garantías relativamente inmediatas según el motor y la configuración. Si la API consulta una réplica retrasada, una caché o un repositorio alimentado mediante eventos, puede haber un intervalo durante el que el dato recién modificado todavía no aparezca.

La solución no consiste necesariamente en eliminar todo retraso, sino en declarar qué frescura necesita cada operación. Una consulta de catálogo puede admitir segundos de desfase; la confirmación de un pago, una reserva o el estado de una orden crítica requiere garantías distintas.

Para observar el comportamiento de las llamadas y diagnosticar fallos sin exponer información sensible, resulta útil el enfoque de cómo registrar las llamadas realizadas a una API.

Rendimiento: evitar que la API convierta la base de datos en un cuello de botella

Una API puede recibir pocas peticiones y aun así perjudicar al sistema corporativo si ejecuta consultas costosas. También puede ser lenta aunque las consultas sean rápidas, por un número excesivo de llamadas, conexiones o transformaciones.

Limitar los datos y medir las consultas

Antes de optimizar código hay que medir qué operaciones tardan más y por qué. Conviene revisar tiempos de consulta, planes de ejecución, índices pertinentes, cantidad de filas examinadas, bloqueos y tamaño de los resultados. El objetivo no es que todas las consultas sean complejas o tengan caché, sino que cada una esté proporcionada a la necesidad real.

Una API no debería devolver miles de registros porque un consumidor olvidó indicar un límite. Los listados necesitan paginación, los filtros deben estar validados y los informes de gran tamaño pueden trasladarse a un proceso asíncrono que deje un resultado recuperable.

Gestionar el número de conexiones

Abrir una conexión nueva al motor por cada operación y no cerrarla correctamente puede agotar recursos. Un grupo de conexiones (pool) permite reutilizarlas, pero no significa que más conexiones siempre mejoren el rendimiento. Deben configurarse límites de concurrencia, tiempos de espera y comportamiento ante saturación, considerando también las demás aplicaciones que utilizan la misma base.

Evitar consultas repetidas y ciclos innecesarios

Un listado de cincuenta incidencias no debería exigir, si puede evitarse, una consulta adicional por cada cliente asociado. Es preferible diseñar una consulta adecuada o una composición controlada de resultados. Del mismo modo, si la API se consume desde varias aplicaciones, conviene evitar que cada pantalla vuelva a solicitar datos invariantes sin necesidad.

Escalar cuando existe un motivo comprobable

Primero hay que corregir consultas deficientes, índices ausentes, resultados excesivos y límites mal configurados. Después puede evaluarse caché, separación de cargas de lectura, tareas asíncronas o réplicas. Esas alternativas introducen nuevas decisiones sobre invalidación, retrasos y recuperación. Una introducción útil al diagnóstico se encuentra en cómo detectar problemas de rendimiento en una base de datos.

Pruebas y puesta en producción: comprobar algo más que el código 200

Que una llamada devuelva 200 OK demuestra muy poco sobre la seguridad y corrección de toda la integración. Hay que probar el contrato, las reglas del negocio y las situaciones que pueden deteriorar o comprometer los datos.

Pruebas funcionales y de autorización

• Consultar un registro existente, otro inexistente y uno perteneciente a una organización diferente.
• Enviar campos obligatorios ausentes, tipos inválidos, valores extremos y parámetros no permitidos.
• Comprobar que una identidad de solo lectura no puede modificar ni eliminar información.
• Verificar que las respuestas nunca incluyen campos internos que no forman parte del contrato.
• Confirmar que los cambios concurrentes no sobrescriben datos sin control.

Pruebas de fallos y reintentos

• Interrumpir la conexión con la base de datos durante una consulta y comprobar la respuesta controlada.
• Repetir una escritura tras simular la pérdida de la respuesta y comprobar que no se duplica.
• Provocar un conflicto de unicidad o versión y verificar su tratamiento.
• Detener una importación a mitad de lote y comprobar que puede reanudarse sin omisiones indebidas.
• Comprobar los límites de paginación, carga simultánea, tiempos de espera y agotamiento del pool.

Preparar los entornos y el despliegue

Las pruebas deberían utilizar entornos separados y datos sintéticos o adecuadamente protegidos. No es buena práctica apuntar desde un ordenador de desarrollo a una base de producción para «probar rápidamente». Las migraciones de esquema deben planificarse teniendo en cuenta que pueden convivir durante un periodo la versión anterior y la nueva de la API.

Antes de publicar, conviene verificar copias de seguridad y recuperación, activar supervisión con umbrales útiles, documentar la reversión del despliegue y comprobar que el procedimiento de rotación de credenciales funciona. La separación de estos entornos se desarrolla con más detalle en cómo organizar entornos de desarrollo, pruebas y producción.

Caso práctico: conectar una aplicación de asistencia con datos corporativos

Una empresa pequeña presta mantenimiento informático a varias organizaciones. Su sistema interno guarda clientes, equipos, contratos e incidencias. Quiere ofrecer a los técnicos una aplicación desde la que puedan consultar equipos asignados y registrar nuevas incidencias sin acceder directamente a la base de datos.

Situación inicial

Los técnicos trabajan con exportaciones de hojas de cálculo. Eso provoca información desactualizada, referencias inconsistentes y dudas sobre qué registros se han modificado. La empresa decide publicar una API limitada en lugar de dar a cada técnico credenciales del motor SQL.

Diseño del primer alcance

1. Identidades: cada técnico inicia sesión y pertenece a una o varias organizaciones autorizadas.
2. Consulta: GET /api/v1/equipos/{id} devuelve solo los datos técnicos que necesita la intervención.
3. Listado: GET /api/v1/equipos?limite=50 utiliza filtrado por el ámbito autorizado y paginación estable.
4. Registro: POST /api/v1/incidencias valida equipo, contrato, categoría e identidad, y utiliza una clave de idempotencia.
5. Confirmación: cada incidencia recibe un identificador estable y una respuesta que confirma su estado real.
6. Auditoría: el servicio registra identificadores de operación, momento, identidad técnica y resultado sin almacenar secretos ni información innecesaria.

Qué ocurre durante una intervención

El técnico abre una ficha. La aplicación solicita la información a la API, que valida su identidad y consulta la vista autorizada. El técnico registra una incidencia: el servicio verifica el equipo y guarda la operación en una transacción. Si se corta la cobertura justo después de la confirmación, la aplicación puede reintentar de forma segura con la misma clave de idempotencia y recuperar la incidencia creada.

Más adelante, la empresa necesita notificar la nueva incidencia a un sistema externo. En lugar de introducir una llamada remota dentro de la transacción y confiar en que siempre habrá conexión, incorpora un proceso de entrega posterior controlado. Así amplía la integración sin convertir el alta de incidencias en una cadena frágil de dependencias.

Cómo comprobar que el proyecto aporta valor

La empresa puede comparar el tiempo necesario para localizar un equipo, los errores de asignación, el número de incidencias duplicadas y la antigüedad de la información antes y después de implantar la solución. También debe medir errores de API, tiempos de respuesta y trabajos pendientes de sincronizar.

Este caso ilustra un criterio esencial: la API debe resolver una necesidad operativa concreta y verificable. No es necesario publicar desde el primer día todas las tablas, ni conectar todos los departamentos ni construir una infraestructura desproporcionada.

Errores habituales al integrar APIs con bases de datos

• Exponer las tablas tal cual: compromete la independencia del contrato, aumenta la información publicada y transmite detalles internos a los consumidores.
• Usar una cuenta administradora: concede al servicio más capacidades de las necesarias y amplifica el daño potencial de un incidente.
• Autorizar solo al iniciar sesión: permite errores de acceso a objetos concretos si no se comprueba cada operación y su ámbito.
• Construir SQL concatenando entradas: introduce riesgo de inyección y dificulta la validación del comportamiento.
• Repetir escrituras sin idempotencia: puede crear duplicados cuando una operación se confirmó pero se perdió su respuesta.
• Descargar tablas completas en cada llamada: desperdicia recursos y puede afectar al resto de aplicaciones corporativas.
• Mezclar cambios locales y llamadas externas como si fueran una sola transacción: produce estados inciertos difíciles de recuperar.
• Ignorar bajas y retrasos de sincronización: genera repositorios locales aparentemente correctos, pero cada vez más desactualizados.
• Registrar respuestas completas sin control: aumenta la exposición de datos personales, secretos e información interna.
• Publicar sin probar la recuperación: convierte una interrupción ordinaria en una intervención manual sobre registros.

Muchas de estas deficiencias no aparecen en una demostración con pocos registros y una sola persona. Se hacen visibles al aumentar los consumidores o cuando el servicio deja de responder. Una vez estabilizada la primera versión, merece la pena revisar las recomendaciones de mantenimiento de integraciones mediante APIs a largo plazo.

Preguntas frecuentes

Conclusión: integrar bien significa controlar el dato durante todo su recorrido

Integrar APIs con bases de datos corporativas no consiste en publicar operaciones SQL bajo direcciones HTTP. Consiste en transformar necesidades empresariales en servicios con permisos claros, contratos estables y resultados verificables.

La mejor primera versión suele ser pequeña: una consulta útil, un conjunto mínimo de campos y una identidad con permisos limitados. A partir de ahí se incorporan escrituras transaccionales, controles de concurrencia, idempotencia, sincronización y observabilidad en función de necesidades reales.

Si la API permite saber quién puede consultar cada registro, qué confirma una operación y cómo recuperarse de un fallo sin perder ni duplicar datos, la empresa dispone de una base sólida para conectar nuevas aplicaciones sin convertir su información en una dependencia incontrolable.