Cómo Instalar y Usar PostgREST API: Guía para Principiantes

¿Alguna vez ha considerado cuánto tiempo dedican los desarrolladores a construir APIs RESTful sobre bases de datos PostgreSQL? A menudo implica escribir código repetitivo para operaciones CRUD, manejar consultas y garantizar la seguridad, tareas que pueden ralentizar el impulso de su proyecto. Aquí es donde entra en juego la API de PostgREST, ofreciendo una alternativa optimizada que convierte su base de datos en una API lista para usar con un esfuerzo mínimo. En esta guía completa, exploraremos la API de PostgREST en profundidad, desde sus conceptos fundamentales hasta su implementación práctica. Ya sea que sea un ingeniero de backend que busca acelerar el desarrollo o un desarrollador full-stack que busca eficiencia, dominar la API de PostgREST puede transformar su flujo de trabajo.

A medida que naveguemos juntos por este tema, compartiré ideas extraídas de la experiencia práctica, asegurando que cada sección se base lógicamente en la anterior. Al concluir, se sentirá equipado para integrar la API de PostgREST en su próximo proyecto. Comencemos con lo esencial.

💡

¿Quiere una excelente herramienta de prueba de API que genere hermosa documentación de API?

¿Quiere una plataforma integrada y todo en uno para que su equipo de desarrolladores trabaje con máxima productividad?

¡Apidog satisface todas sus demandas y reemplaza a Postman a un precio mucho más asequible!

botón

¿Qué es la API de PostgREST? Una visión general

La API de PostgREST es una herramienta independiente que expone automáticamente su base de datos PostgreSQL como un servicio web RESTful completamente funcional. Desarrollada por Beowulf, aprovecha el poder del lenguaje de consulta de PostgreSQL (SQL) para generar puntos finales HTTP dinámicamente, eliminando la necesidad de lógica personalizada del lado del servidor en muchos casos. En esencia, la API de PostgREST interpreta esquemas de bases de datos, tablas, vistas y procedimientos almacenados como recursos de API, permitiéndole realizar operaciones de creación, lectura, actualización y eliminación (CRUD) a través de métodos HTTP estándar como GET, POST, PUT y DELETE.

Lo que hace que la API de PostgREST sea particularmente atractiva es su adhesión a los principios REST mientras incorpora características avanzadas de PostgreSQL como la Seguridad a Nivel de Fila (RLS) para un control de acceso granular. Por ejemplo, puede consultar datos con filtros, ordenación y paginación utilizando parámetros de URL, sin necesidad de middleware adicional. Este enfoque no solo reduce la complejidad del código, sino que también asegura que su API permanezca sincronizada con los cambios de la base de datos automáticamente.

En un panorama dominado por ORMs y frameworks de API, la API de PostgREST destaca por su filosofía de "base de datos primero". Soporta documentación OpenAPI (Swagger) de forma predeterminada, lo que la hace amigable para los desarrolladores para la integración con herramientas como Apidog o Swagger UI. Si gestiona aplicaciones intensivas en datos (piense en paneles de análisis, backends móviles o microservicios), la API de PostgREST proporciona una solución ligera y de alto rendimiento que escala con la robustez de PostgreSQL. A medida que avancemos, verá cómo esta API une la capa de datos y las aplicaciones cliente sin problemas.

Primeros pasos con la API de PostgREST: Instalación y configuración

Para comenzar a trabajar con la API de PostgREST, se requiere una instancia de PostgreSQL, ya que sirve como base. Afortunadamente, la configuración es sencilla, especialmente al usar herramientas de contenerización como Docker, que aíslan las dependencias y simplifican la implementación. Comience asegurándose de que Docker Desktop esté instalado en su máquina; descárguelo del sitio web oficial para su sistema operativo (macOS, Windows o Linux).

Una vez que Docker esté listo, descargue las imágenes necesarias. Abra Docker Desktop, navegue a la barra de búsqueda e instale la imagen "postgrest/postgrest" para el propio servidor API. De manera similar,

busque e instale "dpage/pgadmin4" para gestionar su base de datos PostgreSQL visualmente.

y "postgres:alpine" para un contenedor PostgreSQL ligero. Estos componentes forman el ecosistema alrededor de la API de PostgREST.

Para una configuración manual de PostgreSQL a través de la terminal (Recomendado), ejecute el siguiente comando para iniciar un contenedor:

docker run --name postgres-1 -e POSTGRES_PASSWORD=password -d -p 5431:5432 postgres:alpine

Aquí, reemplace "password" con un valor seguro. El comando inicia PostgreSQL en el puerto 5431, mapeándolo al 5432 interno. Si tiene éxito, Docker devolverá un ID de contenedor (una cadena alfanumérica larga); anótelo para verificación. Ejecute docker ps para confirmar el estado del contenedor.

verificar la instalación de postgres en docker

Para verificar los roles de usuario, que son cruciales para la configuración de la API de PostgREST, ingrese al shell del contenedor:

docker exec -it <container_id> sh

Sustituya <container_id> por su ID o nombre de contenedor. Dentro del shell, conéctese a PostgreSQL:

psql -U postgres -d postgres

(Asumiendo "postgres" como usuario predeterminado; ajuste si está personalizado. Como el mío que fue cambiado a username) Luego, liste los roles con \du. Esta salida, incluyendo nombres de roles como "postgres" o personalizados, se referenciará más adelante. Puede crear usuarios adicionales aquí y asignar permisos, como otorgar SELECT, INSERT, UPDATE o DELETE en esquemas.

Con estos requisitos previos establecidos, está listo para orquestar su entorno utilizando Docker Compose, un archivo YAML que define aplicaciones multi-contenedor. Cree un docker-compose.yaml en su directorio de proyecto:

version: "3.9"
services:
  postgres_host:
    image: postgres:alpine
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5431:5432"
  pgadmin:
    image: dpage/pgadmin4
    ports:
      - "5050:80"
    depends_on:
      - postgres_host
    environment:
      PGADMIN_DEFAULT_EMAIL: postgres@pgadmin.com
      PGADMIN_DEFAULT_PASSWORD: postgres
  postgrest:
    image: postgrest/postgrest
    depends_on:
      - postgres_host
    ports:
      - "3000:3000"
    environment:
      PGRST_DB_URI: "postgres://username:password@postgres_host:5432/postgres"
      PGRST_DB_SCHEMA: "public"
      PGRST_DB_ANON_ROLE: "username"
volumes:
  pgdata:

Personalice "username" y "password" para que coincidan con su configuración, y establezca PGRST_DB_ANON_ROLE a un rol de su salida de \du para acceso anónimo. Esta configuración enlaza PostgreSQL, pgAdmin y el servidor API de PostgREST. Guarde el archivo, luego en su terminal (por ejemplo, el integrado de VS Code, después de instalar la extensión de Docker), ejecute:

docker compose up --build

Esto construye e inicia los servicios. Acceda a pgAdmin en `http://localhost:5050` usando las credenciales del YAML, agregue un servidor llamado "postgres_host" con detalles de conexión (Hostname: postgres_host, Port: 5432, Username: username, Password: password), y guarde. Ahora tiene una API de PostgREST en funcionamiento en `http://localhost:3000`, lista para interacciones con la base de datos.

ejecutando contenedores docker en vs code

Construyendo un Proyecto de Ejemplo: Pruebas Paso a Paso de la API de PostgREST

Para apreciar verdaderamente la API de PostgREST, construyamos un proyecto práctico: una sencilla API de base de datos de recursos humanos para gestionar registros de empleados. Este ejemplo demuestra operaciones CRUD en una tabla "humans", utilizando Docker para la orquestación y Apidog para las pruebas de API.

Paso 1: Prepare su entorno

Con Docker Desktop instalado y las imágenes descargadas (PostgREST, pgAdmin4, postgres:alpine), ejecute el contenedor inicial de PostgreSQL como se describió anteriormente. Verifique con `docker ps` y anote los roles de usuario a través de `\du`.

Paso 2: Componga su pila

En un editor de código como VS Code (mejorado con la extensión de Docker para una gestión de contenedores sin problemas), elabore el archivo `docker-compose.yaml` anterior. Asegúrese de que los nombres de las imágenes se alineen con precisión; las discrepancias pueden detener el inicio. Ajuste los puertos si es necesario, pero mantenga el puerto externo de PostgreSQL (5431) consistente con su configuración manual. Inicie con `docker compose up --build`. Monitoree los registros en busca de errores; un inicio exitoso muestra los servicios vinculados a los puertos 5431 (DB), 5050 (pgAdmin) y 3000 (PostgREST).

Paso 3: Configure pgAdmin y cree la tabla

Navegue a `http://localhost:5050`, inicie sesión con PGADMIN_DEFAULT_EMAIL y PASSWORD del YAML.

iniciar sesión en pgadmin4 alojado en docker

Bajo el panel de control,

añada un nuevo servidor: Nómbrelo "postgres_host",

luego en la pestaña Conexión, ingrese Hostname: postgres_host, Port: 5432, Username: username, Password: password. Guarde para acceder a la interfaz.

guardar la nueva configuración de la base de datos postgres

Cree una tabla: Vaya a Databases > postgres > Schemas > public > Tables, haga clic derecho en Tables y seleccione Create > Table. Nómbrela "humans". En Columns, añada:

id: INTEGER, No Nulo, Clave Primaria
name: VARCHAR(50), No Nulo
job: VARCHAR(50)

Haga clic en Guardar. Para insertar datos, haga clic derecho en la tabla "humans" > Scripts > INSERT Script. Modifique con SQL de ejemplo, por ejemplo:

INSERT INTO public.humans (id, name, job) VALUES (1, 'Steph Curry', 'Pro Basketball Player');

Ejecute para persistir el registro.

Paso 4: Verifique la disponibilidad de la API de PostgREST

Abra `http://localhost:3000` en su navegador. Debería ver un documento de especificación Swagger 2.0 que enumera recursos como /humans, lo que confirma que la API de PostgREST está operativa y es consciente del esquema.

Paso 5: Pruebe con Apidog

Inicie Apidog, cree un nuevo proyecto y añada una solicitud GET a `http://localhost:3000/humans` (reemplace "humans" con el nombre de su tabla). Envíe la solicitud; devolverá JSON como:

[
  {
    "id": 1,
    "name": "Steph Curry",
    "job": "Pro Basketball Player"
  }
]

realizando una solicitud get en apidog con postgrest

Para consultar, añada un Parámetro de Consulta: Clave "name", Valor "eq.Steph Curry" (donde "eq" denota igualdad). Esto filtra los registros coincidentes; los que no coinciden devuelven arrays vacíos.

probando con postgrest con datos incorrectos — Usando datos incorrectos para realizar una búsqueda

usando datos correctos para realizar una búsqueda en apidog con la api de postgrest — Usando la información correcta para realizar una búsqueda

Paso 6: Explore las operaciones CRUD

La API de PostgREST destaca en operaciones CRUD completas. Para POST (crear), use el cuerpo de Apidog como JSON: `{"name": "New Employee", "job": "Developer"}` a `http://localhost:3000/humans`. PUT actualiza a través de `http://localhost:3000/humans?id=eq.1` con datos parcheados. DELETE usa `http://localhost:3000/humans?id=eq.1`. Filtros avanzados como la ordenación (`order=name.asc`) o los límites (`limit=5`) mejoran la usabilidad. Para ejemplos exhaustivos, consulte la documentación oficial en https://docs.postgrest.org/en/v14/references/api/tables_views.html.

Este proyecto, que abarca menos de una hora, ilustra la destreza de la API de PostgREST en la creación rápida de prototipos. Escálelo añadiendo políticas RLS en PostgreSQL para un acceso seguro basado en roles.

Preguntas Frecuentes

P1. ¿Cuáles son los requisitos del sistema para ejecutar la API de PostgREST?

Resp: La API de PostgREST requiere PostgreSQL 9.4 o posterior, con Docker recomendado para configuraciones en contenedores. Se ejecuta de manera eficiente en hardware modesto, necesitando al menos 512 MB de RAM para operaciones básicas.

P2. ¿Puede la API de PostgREST manejar consultas complejas más allá del CRUD básico?

Resp: Sí, soporta todas las capacidades SQL de PostgreSQL a través de llamadas RPC embebidas y vistas, permitiendo uniones, agregaciones y funciones personalizadas expuestas como puntos finales.

P3. ¿Cómo garantiza la API de PostgREST la seguridad de los datos?

Resp: Se integra de forma nativa con la Seguridad a Nivel de Fila de PostgreSQL y los permisos basados en roles, aplicando controles de acceso a nivel de base de datos sin vulnerabilidades del lado de la API.

P4. ¿Es la API de PostgREST adecuada para entornos de producción?

Resp: Absolutamente, con características como autenticación JWT, aislamiento de esquemas y escalado horizontal a través de múltiples instancias. Monitoree el rendimiento y aplique RLS para el cumplimiento.

P5. ¿Cómo integro la API de PostgREST con frameworks frontend?

Resp: Use clientes HTTP como Axios o Fetch; genere tipos TypeScript a partir de especificaciones OpenAPI para la seguridad de tipos en aplicaciones React, Vue o Angular.

Conclusión

Al reflexionar sobre nuestra exploración, la API de PostgREST emerge como una solución elegante para el desarrollo impulsado por bases de datos, convirtiendo las fortalezas de PostgreSQL en servicios web accesibles. Desde una configuración sencilla hasta consultas sofisticadas, le permite entregar APIs robustas con menos sobrecarga. Le animo a replicar el proyecto de ejemplo y a experimentar más, quizás extendiéndolo con autenticación. A medida que sus aplicaciones evolucionen, la API de PostgREST demostrará ser un aliado indispensable para mantener la agilidad y la fiabilidad.

💡

botón