Manual de uso del API de Galerías (solo lectura)

El API de galerías expone endpoints de solo lectura para consultar galerías de imágenes. Todas las rutas viven bajo /api/gallery/* y devuelven JSON.

Autenticación

Incluye Authorization: Bearer <token> en cada solicitud.
El token debe estar activo y tener permisos sobre el recurso que consultas.
Aunque los endpoints actuales no requieren cuerpo, mantén Content-Type: application/json en caso de enviar parámetros serializados.

Permisos

read: permite ejecutar peticiones GET.

Si el token está vencido, inactivo o carece del permiso read, la respuesta será 401 o 403.

Códigos de respuesta comunes

200 OK: respuesta exitosa.
400 Bad Request: parámetros inválidos.
401 / 403: token ausente, inválido o sin permisos.
404 Not Found: recurso inexistente.
405 Method Not Allowed: se intentó un método distinto de GET.
500 Internal Server Error: error no controlado en el servidor.

Galerías — `/api/gallery`

GET listado

Devuelve todas las galerías accesibles para el token. Las imágenes no se incluyen en el listado para reducir el tamaño de la respuesta.

Query params

limit (número, opcional): máximo de resultados (1–100).

Ejemplo

bash

curl "https://cms.begraffic.com/api/gallery?limit=10" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "count": 2,
  "galleries": [
    {
      "id": "galeria-productos-2024",
      "name": "Galería de Productos 2024",
      "description": "Imágenes de nuestros productos más destacados",
      "imageCount": 5,
      "createdAt": "2024-05-01T10:00:00.000Z",
      "updatedAt": "2024-05-02T12:30:00.000Z"
    },
    {
      "id": "galeria-eventos-2024",
      "name": "Galería de Eventos 2024",
      "description": "Fotos de nuestros eventos corporativos",
      "imageCount": 12,
      "createdAt": "2024-05-15T08:00:00.000Z",
      "updatedAt": "2024-05-20T09:30:00.000Z"
    }
  ]
}

GET detalle

GET /api/gallery?id=<id>

Devuelve una galería específica que coincida con el ID. Este endpoint incluye todas las imágenes con sus variantes.

Respuesta

json

{
  "gallery": {
    "id": "galeria-productos-2024",
    "name": "Galería de Productos 2024",
    "description": "Imágenes de nuestros productos más destacados",
    "images": [
      {
        "variants": {
          "original": {
            "url": "https://cdn.begraffic.com/galleries/uuid1/original.jpg",
            "width": 1920,
            "height": 1080,
            "size": 245760,
            "contentType": "image/jpeg"
          },
          "medium": {
            "url": "https://cdn.begraffic.com/galleries/uuid1/medium.webp",
            "width": 1280,
            "height": 720,
            "size": 156789,
            "contentType": "image/webp"
          },
          "small": {
            "url": "https://cdn.begraffic.com/galleries/uuid1/small.webp",
            "width": 640,
            "height": 360,
            "size": 45678,
            "contentType": "image/webp"
          },
          "thumbnail": {
            "url": "https://cdn.begraffic.com/galleries/uuid1/thumbnail.webp",
            "width": 300,
            "height": 300,
            "size": 12345,
            "contentType": "image/webp"
          }
        },
        "previewUrl": "https://cdn.begraffic.com/galleries/uuid1/medium.webp"
      }
    ],
    "createdAt": "2024-05-01T10:00:00.000Z",
    "updatedAt": "2024-05-02T12:30:00.000Z"
  }
}

Estructura de Imágenes

Cada imagen en una galería incluye múltiples variantes optimizadas:

Variantes disponibles

original: Imagen en tamaño y formato original
medium: Imagen redimensionada a 1280px de ancho máximo
small: Imagen redimensionada a 640px de ancho máximo
thumbnail: Imagen cuadrada de 300x300px

Campos de cada variante

url: URL pública de la imagen
width: Ancho en píxeles
height: Alto en píxeles
size: Tamaño del archivo en bytes
contentType: Tipo MIME (image/jpeg, image/webp, etc.)

Campo previewUrl

Cada imagen incluye un campo previewUrl que apunta a la variante medium (o original si medium no está disponible) para facilitar la visualización.

Buenas prácticas

Utiliza previewUrl para mostrar vistas previas de las imágenes.
Las variantes thumbnail son ideales para listados y grids.
Las variantes medium son perfectas para vistas detalladas.
Las variantes original solo deben usarse cuando necesites la máxima calidad.
Maneja específicamente los códigos 404 (galería no encontrada) y 405 (método no permitido) en tus integraciones.
Si llegas a necesitar operaciones de escritura, deberás coordinar con el equipo para habilitar endpoints adicionales.