Cómo conectar una API con una base de datos

1. ¿Qué significa conectar una API con una base de datos?

En una aplicación web, la API permite que otros sistemas soliciten operaciones o información al backend. La base de datos almacena la información que la aplicación necesita conservar.

Conectar una API con una base de datos significa configurar el backend para que pueda consultar y modificar los datos almacenados y exponer esas operaciones mediante endpoints.

Por ejemplo, una tienda en línea puede necesitar una API que permita:

• Consultar los productos disponibles.
• Registrar nuevos productos.
• Actualizar sus precios.
• Eliminar productos.
• Consultar el historial de ventas.

La API recibe las solicitudes, el backend ejecuta la lógica necesaria y la base de datos almacena o devuelve la información correspondiente.

2. Arquitectura de una aplicación web

Una arquitectura común utiliza tres componentes principales:

2. Arquitectura de una aplicación web

Una arquitectura común utiliza tres componentes principales:

┌──────────────────────────────┐
│           FRONTEND           │
│                              │
│ Interfaz con la que          │
│ interactúa el usuario.       │
└──────────────────────────────┘
               ↕
┌──────────────────────────────┐
│        BACKEND / API         │
│                              │
│ Recibe solicitudes HTTP,     │
│ valida datos y aplica las    │
│ reglas del sistema.          │
└──────────────────────────────┘
               ↕
┌──────────────────────────────┐
│        BASE DE DATOS         │
│                              │
│ Almacena y consulta la       │
│ información persistente.     │
└──────────────────────────────┘

¿Cómo se comunican?

1. Frontend → Backend/API: el frontend envía una solicitud HTTP cuando el usuario realiza una acción.
2. Backend/API → Base de datos: el backend consulta o modifica los datos según la operación solicitada.
3. Base de datos → Backend/API: la base de datos devuelve los resultados de la consulta.
4. Backend/API → Frontend: el backend envía una respuesta, normalmente en formato JSON cuando se trata de una API web.

Importante: el frontend normalmente no debe conectarse directamente a una base de datos privada. El backend controla el acceso, valida las solicitudes y aplica las reglas de seguridad.

Cada componente tiene una responsabilidad distinta:

• Frontend: muestra los datos y permite al usuario interactuar con el sistema.
• Backend: recibe las solicitudes, valida la información, aplica las reglas de negocio y se comunica con la base de datos.
• Base de datos: guarda, organiza y recupera la información.

La API suele ser una parte del backend, no necesariamente una aplicación independiente.

3. ¿Cómo se comunican estos componentes?

Imaginemos que el usuario quiere consultar los productos de una tienda.

1. El frontend envía una solicitud HTTP al endpoint GET /api/productos.
2. El backend recibe la solicitud y determina qué operación debe realizar.
3. El backend consulta la base de datos.
4. La base de datos devuelve los registros encontrados.
5. El backend transforma los resultados al formato esperado, por ejemplo JSON.
6. El backend devuelve una respuesta HTTP.
7. El frontend recibe la respuesta y muestra los productos.

La comunicación entre el frontend y la API suele realizarse mediante HTTP. La comunicación entre el backend y la base de datos utiliza el controlador, conector u ORM correspondiente.

Importante: el frontend normalmente no debe conectarse directamente a una base de datos privada. El backend debe controlar el acceso para proteger las credenciales, validar las operaciones y aplicar los permisos correspondientes.

4. Paso 1: preparar la base de datos

Antes de conectar una API, debe existir una base de datos accesible y una estructura que represente la información que se desea almacenar.

Por ejemplo, una tabla Productos podría tener esta estructura:

Campo	Tipo de dato	Propósito
Id	Entero	Identifica cada producto.
Nombre	Texto	Almacena el nombre del producto.
Precio	Decimal	Almacena su precio.
Existencia	Entero	Representa las unidades disponibles.

El diseño real dependerá de los requisitos del sistema y de las reglas de la base de datos.

Antes de continuar, comprueba que:

• La base de datos exista.
• Las tablas estén creadas.
• Las columnas y sus tipos sean adecuados.
• Las claves primarias y relaciones estén configuradas.
• El usuario de base de datos tenga los permisos necesarios.

5. Paso 2: configurar la conexión en el backend

El backend necesita conocer cómo acceder a la base de datos.

Normalmente se requieren datos como:

• Servidor o dirección del host.
• Puerto, cuando corresponda.
• Nombre de la base de datos.
• Usuario.
• Contraseña.
• Opciones de conexión y seguridad.

Estos datos se suelen almacenar en variables de entorno o en un sistema de configuración seguro.

Ejemplo conceptual:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=tienda
DB_USER=usuario_app
DB_PASSWORD=contraseña_segura

Este ejemplo ilustra la configuración de una conexión a PostgreSQL. Los parámetros cambian según el motor de base de datos y el controlador utilizado.

Buenas prácticas:

• No escribir contraseñas directamente en el código fuente.
• No publicar archivos .env con credenciales reales.
• Usar un usuario de base de datos con los permisos mínimos necesarios.
• Configurar correctamente las credenciales en producción.

6. Paso 3: utilizar un controlador u ORM

El backend necesita un mecanismo para comunicarse con la base de datos.

Hay dos enfoques comunes.

Controlador o driver

Permite ejecutar consultas mediante una biblioteca específica del motor de base de datos.

Por ejemplo, se pueden ejecutar consultas SQL parametrizadas para buscar, insertar, modificar o eliminar registros.

ORM (Object-Relational Mapper)

Un ORM permite trabajar con los datos mediante objetos y modelos del lenguaje de programación, traduciendo muchas operaciones a consultas de base de datos.

Algunos ejemplos son:

• Entity Framework Core para .NET.
• Prisma para JavaScript y TypeScript.
• SQLAlchemy para Python.
• Hibernate para Java.

Un ORM puede facilitar el trabajo con entidades y relaciones, pero no elimina la necesidad de comprender la base de datos ni las consultas que se ejecutan.

7. Paso 4: crear los endpoints de la API

Un endpoint es una dirección de la API que permite realizar una operación mediante un método HTTP.

Para una entidad Productos, una API podría definir los siguientes endpoints:

Método	Endpoint	Operación
GET	/api/productos	Consultar todos los productos.
GET	/api/productos/15	Consultar un producto por su identificador.
POST	/api/productos	Registrar un producto.
PUT	/api/productos/15	Reemplazar los datos de un producto.
PATCH	/api/productos/15	Modificar parcialmente un producto.
DELETE	/api/productos/15	Eliminar un producto.

Estas rutas son convenciones habituales, no una obligación de HTTP. Cada API define sus propias rutas y operaciones.

El backend debe comprobar que la operación solicitada esté permitida y que los datos cumplan las reglas del sistema.

8. Paso 5: consultar la base de datos

Cuando llega una solicitud, el backend ejecuta la operación correspondiente.

Por ejemplo, para consultar productos, la lógica podría expresarse en SQL así:

SELECT Id, Nombre, Precio, Existencia
FROM Productos;

El controlador u ORM ejecuta la consulta y obtiene los registros.

El backend puede convertir los resultados en una estructura que luego se devuelve como JSON:

[
  {
    "id": 1,
    "nombre": "Llanta deportiva",
    "precio": 25000,
    "existencia": 12
  },
  {
    "id": 2,
    "nombre": "Llanta urbana",
    "precio": 18000,
    "existencia": 7
  }
]

El JSON es el formato de la respuesta, no la base de datos en sí. La información persistente sigue almacenada en la base de datos.

9. Paso 6: devolver una respuesta HTTP

Después de ejecutar la operación, el backend debe devolver una respuesta apropiada.

Por ejemplo:

Situación	Respuesta habitual
Consulta exitosa	200 OK
Registro creado	201 Created
Operación exitosa sin contenido que devolver	204 No Content
Datos inválidos	400 Bad Request o 422 Unprocessable Content
Usuario no autenticado	401 Unauthorized
Usuario sin permiso	403 Forbidden
Recurso inexistente	404 Not Found
Conflicto con el estado del recurso	409 Conflict
Error inesperado del servidor	500 Internal Server Error

La elección exacta depende de la operación y del diseño de la API.

Por ejemplo, si el frontend solicita un producto que no existe, el backend puede devolver 404. Si la consulta a la base de datos falla por un problema inesperado, podría devolver 500.

No conviene enviar detalles internos, consultas SQL o credenciales en los mensajes de error que recibe el cliente.

10. Paso 7: consumir la API desde el frontend

El frontend solicita los datos al backend y utiliza la respuesta para actualizar la interfaz.

Conceptualmente, el proceso es:

Usuario abre la lista de productos
            ↓
Frontend solicita GET /api/productos
            ↓
Backend consulta la base de datos
            ↓
Backend devuelve JSON y un código HTTP
            ↓
Frontend interpreta la respuesta
            ↓
La interfaz muestra los productos

El frontend no necesita conocer las tablas internas ni las credenciales de la base de datos. Solo necesita conocer el contrato de la API: las rutas disponibles, los datos esperados y las respuestas posibles.

11. Cómo diagnosticar problemas de conexión

Cuando una API no logra obtener o guardar información, conviene investigar por capas.

La API no puede conectarse a la base de datos

Comprueba:

• Que el servidor de base de datos esté activo.
• Que el host y el puerto sean correctos.
• Que el nombre de la base de datos exista.
• Que las credenciales sean válidas.
• Que los permisos y las reglas de red permitan la conexión.

La API responde, pero no devuelve los datos esperados

Comprueba:

• Que los registros existan.
• Que la consulta sea correcta.
• Que los filtros no excluyan los resultados.
• Que la respuesta se construya con los campos esperados.
• Que no exista una diferencia entre la estructura de la base de datos y los modelos utilizados por el backend.

El frontend no logra comunicarse con la API

Comprueba:

• Que la URL del endpoint sea correcta.
• Que el backend esté activo.
• Que el método HTTP sea el adecuado.
• Que los datos enviados tengan el formato esperado.
• Que la configuración de CORS sea correcta cuando el navegador realiza solicitudes entre distintos orígenes.

La API devuelve un error 500

Comprueba:

• Los registros del backend.
• La excepción original.
• Las consultas ejecutadas.
• El estado de la base de datos.
• Las dependencias y configuraciones involucradas.

Un 500 no significa necesariamente que la base de datos esté caída: el fallo podría originarse en cualquier parte del procesamiento del backend.

12. Buenas prácticas

• Separar responsabilidades: evitar que la interfaz contenga credenciales o lógica de acceso directo a una base de datos privada.
• Validar los datos: comprobar las entradas antes de ejecutar operaciones.
• Utilizar consultas parametrizadas: reducir el riesgo de inyección SQL.
• Controlar los permisos: verificar la autorización antes de acceder o modificar información.
• Manejar errores: devolver códigos HTTP apropiados y registrar detalles técnicos de forma segura.
• Gestionar las conexiones: utilizar mecanismos adecuados de apertura, reutilización y cierre de conexiones.
• Proteger las credenciales: mantenerlas fuera del código público y del control de versiones.
• Utilizar transacciones cuando corresponda: mantener la consistencia de operaciones que involucran varios cambios relacionados.
• Documentar la API: especificar endpoints, métodos, parámetros, cuerpos y respuestas.
• Probar las operaciones: verificar consultas, registros, modificaciones, eliminaciones y casos de error.

Conclusión

Conectar una API con una base de datos implica configurar el acceso desde el backend, ejecutar operaciones mediante un controlador u ORM, definir endpoints y devolver respuestas que el frontend pueda interpretar.

El flujo fundamental es:

Frontend → API/backend → Base de datos → API/backend → Frontend

Comprender esta arquitectura permite aplicar los mismos conceptos en distintos lenguajes, frameworks y motores de bases de datos. Lo que cambia entre tecnologías es la implementación concreta; la separación de responsabilidades y el flujo de comunicación siguen siendo similares.