MinIO Example - Proyecto Personal

Pruebas con MinIO y ASP.NET Core.

🚀 Setup

1. Levantar MinIO

docker run -d `
  --name minio `
  -p 9000:9000 `
  -p 9001:9001 `
  -e MINIO_ROOT_USER=minioadmin `
  -e MINIO_ROOT_PASSWORD=minioadmin `
  -v /minio/data:/data `
  quay.io/minio/minio server /data --console-address ":9001"

Explicación de parámetros:

-d : Ejecuta el contenedor en modo detached (en segundo plano)
--name minio : Asigna el nombre "minio" al contenedor
-p 9000:9000 : Mapea el puerto 9000 del contenedor al puerto 9000 del host (API de MinIO)
-p 9001:9001 : Mapea el puerto 9001 del contenedor al puerto 9001 del host (Consola web)
-e MINIO_ROOT_USER=minioadmin : Establece el usuario administrador
-e MINIO_ROOT_PASSWORD=minioadmin : Establece la contraseña del administrador
-v /minio/data:/data : Monta un volumen para persistir los datos
quay.io/minio/minio : Imagen oficial de MinIO
server /data : Inicia MinIO como servidor de almacenamiento usando /data como directorio de almacenamiento
--console-address ":9001" : Especifica la dirección de la consola web de administración

2. Configurar MinIO

Console: http://localhost:9001 (minioadmin / minioadmin)
Crear bucket mybucket
Subir archivos de prueba

3. Ejecutar API

cd minIO-example.API
dotnet run

Swagger: http://localhost:5135/swagger

📋 Endpoints Principales

Endpoint	Qué hace
`GET /api/example/presigned-url`	URL para descargar archivo
`GET /api/example/list-objects`	Listar archivos del bucket
`POST /api/example/upload`	Subir archivo

🧪 Para Probar

Swagger UI: http://localhost:5135/swagger
Archivo .http: Usar minIO-example.API.http en VS Code

🐳 Docker

docker restart minio  # Reiniciar
docker logs minio     # Ver logs
docker stop minio     # Detener

🧪 Pruebas

Swagger UI: http://localhost:5135/swagger
Archivo .http: minIO-example.API.http en VS Code
Usuario: minioadmin
Contraseña: minioadmin

3. Crear bucket inicial

Ve a http://localhost:9001
Inicia sesión con minioadmin / minioadmin
Crea un bucket llamado mybucket
Sube algunos archivos de prueba (opcional)

4. Ejecutar la API

cd minIO-example.API
dotnet run

La API estará disponible en:

API: http://localhost:5135
Swagger UI: http://localhost:5135/swagger

📋 Endpoints Disponibles

🔽 Descargar / Consultar Imágenes

Método	Endpoint	Descripción
`GET`	`/api/ImageDownload/url`	Genera URL presignada (1 hora) con verificación
`GET`	`/api/ImageDownload/url-custom-expiry`	URL presignada con expiración personalizada
`GET`	`/api/ImageDownload/secure-url`	URL segura + metadatos (solo si existe)
`GET`	`/api/ImageDownload/validate`	Validación completa con detalles
`GET`	`/api/ImageDownload/exists`	Verifica si existe una imagen (true/false)
`GET`	`/api/ImageDownload/list`	Lista todas las imágenes en un bucket
`GET`	`/api/ImageDownload/bucket-exists`	Verifica si existe un bucket
`GET`	`/api/ImageDownload/info`	Obtiene metadatos de una imagen específica

📤 Subir Imágenes

Método	Endpoint	Descripción
`POST`	`/api/ImageUpload/upload`	Sube imagen con nombre original
`POST`	`/api/ImageUpload/upload-custom-name`	Sube imagen con nombre personalizado
`POST`	`/api/ImageUpload/upload-with-folder`	Sube imagen organizándola en carpetas
`GET`	`/api/ImageUpload/upload-url`	Genera URL presignada para upload

🔒 Endpoint Recomendado: `/secure-url`

GET /api/ImageDownload/secure-url?bucketID=mybucket&imageName=myimage.jpg&expirySeconds=3600

Respuesta si existe:

{
  "url": "https://localhost:9000/mybucket/myimage.jpg?X-Amz-Algorithm=...",
  "expiresIn": 3600,
  "expiresAt": "2025-10-27T15:30:00Z",
  "imageInfo": {
    "name": "myimage.jpg",
    "size": 1024768,
    "sizeFormatted": "1.0 MB",
    "contentType": "image/jpeg",
    "lastModified": "2025-10-27T14:30:00Z",
    "eTag": "abc123..."
  },
  "bucketName": "mybucket",
  "status": "Success"
}

Respuesta si no existe:

HTTP 404 - "Image 'myimage.jpg' does not exist in bucket 'mybucket'"

🔍 Validación Completa: `/validate`

GET /api/ImageDownload/validate?bucketID=mybucket&imageName=myimage.jpg

Respuesta detallada:

{
  "exists": false,
  "reason": "ImageNotFound",
  "message": "Image 'myimage.jpg' does not exist in bucket 'mybucket'",
  "bucketName": "mybucket",
  "imageName": "myimage.jpg",
  "isImageExtension": true
}

🧪 Ejemplos de Uso

Casos de Uso Principales

# 1. Validar imagen antes de generar URL
curl "http://localhost:5135/api/ImageDownload/validate?bucketID=mybucket&imageName=myimage.jpg"

# 2. Obtener URL segura (solo si existe)
curl "http://localhost:5135/api/ImageDownload/secure-url?bucketID=mybucket&imageName=myimage.jpg&expirySeconds=7200"

# 3. Verificación rápida de existencia
curl "http://localhost:5135/api/ImageDownload/exists?bucketID=mybucket&imageName=myimage.jpg"

# 4. Listar todas las imágenes en un bucket
curl "http://localhost:5135/api/ImageDownload/list?bucketID=mybucket"

📤 Subir Imágenes

# Subir imagen con nombre original
curl -X POST "http://localhost:5135/api/ImageUpload/upload?bucketID=mybucket" \
  -F "file=@myimage.jpg"

# Subir con nombre personalizado
curl -X POST "http://localhost:5135/api/ImageUpload/upload-custom-name?bucketID=mybucket&customName=custom_image" \
  -F "file=@myimage.jpg"

# Subir organizando en carpetas
curl -X POST "http://localhost:5135/api/ImageUpload/upload-with-folder?bucketID=mybucket&folder=photos/2025" \
  -F "file=@myimage.jpg"

Endpoints con Verificación

# URL presignada con verificación automática
curl "http://localhost:5135/api/ImageDownload/url?bucketID=mybucket&imageName=myimage.jpg"

# URL presignada sin verificación (comportamiento anterior)
curl "http://localhost:5135/api/ImageDownload/url?bucketID=mybucket&imageName=myimage.jpg&skipExistenceCheck=true"

# URL con expiración personalizada y verificación
curl "http://localhost:5135/api/ImageDownload/url-custom-expiry?bucketID=mybucket&imageName=myimage.jpg&expirySeconds=1800"

Usando el archivo .http

Abre minIO-example.API.http en VS Code y usa los ejemplos incluidos.

Usando Swagger UI

Ve a http://localhost:5135/swagger para una interfaz interactiva.

⚙️ Configuración

Variables de entorno (opcional)

Puedes sobrescribir la configuración usando variables de entorno:

export MINIO_ENDPOINT=localhost:9000
export MINIO_ACCESS_KEY=minioadmin
export MINIO_SECRET_KEY=minioadmin

Configuración en appsettings.json

{
  "MinIO": {
    "Endpoint": "localhost:9000",
    "AccessKey": "minioadmin",
    "SecretKey": "minioadmin",
    "UseSSL": false
  }
}

🐳 Comandos Docker Útiles

# Ver logs de MinIO
docker logs minio

# Detener MinIO
docker stop minio

# Reiniciar MinIO
docker restart minio

# Eliminar contenedor (¡cuidado! se pierden los datos)
docker rm -f minio

# Ver contenedores en ejecución
docker ps

📁 Estructura del Proyecto

minIO-example/
├── minIO-example.API/
│   ├── Controllers/
│   │   ├── ImageDownloadController.cs    # 🔽 Descargar imágenes (URLs seguras)
│   │   └── ImageUploadController.cs      # 📤 Subir imágenes
│   ├── Program.cs                        # Configuración de la app
│   ├── minIO-example.API.http            # Ejemplos de requests
│   └── minIO-example.API.csproj
└── README.md                             # Este archivo

Características Principales

✅ URLs Seguras

Verificación automática de existencia antes de generar URLs
Respuestas 404 Not Found en lugar de URLs inválidas
Metadatos incluidos en respuestas de URLs seguras

🔍 Validación Robusta

Endpoint /validate con información detallada
Verificación de buckets y objetos por separado
Información sobre tipo de archivo y extensiones

📸 Gestión de Imágenes

Soporte para formatos: JPG, JPEG, PNG, GIF, BMP, WEBP
Organización en carpetas
Nombres personalizados para archivos
Información de tamaño formateada (KB, MB, GB)

🔄 Compatibilidad

Endpoints existentes mantienen compatibilidad
Parámetro opcional para omitir verificaciones
Migración gradual sin romper funcionalidad existente

🔧 Tecnologías Utilizadas

ASP.NET Core 9.0 - Framework web
MinIO .NET Client - Cliente oficial de MinIO
Swagger/OpenAPI - Documentación de API
Docker - Contenedor para MinIO

📚 Recursos Adicionales

🔐 Seguridad

⚠️ Importante: Las credenciales por defecto (minioadmin/minioadmin) son solo para desarrollo.

Para producción:

Cambia las credenciales
Habilita HTTPS
Configura políticas de acceso apropiadas
Usa variables de entorno para secrets

🐛 Troubleshooting

MinIO no se conecta

Verifica que el contenedor esté ejecutándose: docker ps
Verifica los puertos: netstat -tulpn | grep :9000

Error de SSL

Asegúrate de que WithSSL(false) esté configurado en desarrollo
Para producción, configura certificados apropiados

Bucket no existe

Crea el bucket desde MinIO Console (http://localhost:9001)
Usa /bucket-exists para verificar antes de usar

Imagen no encontrada

Usa /validate para diagnóstico completo
Usa /list para ver qué imágenes están disponibles
Verifica extensiones válidas: JPG, JPEG, PNG, GIF, BMP, WEBP

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
minIO-example.API		minIO-example.API
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
minIO-example.sln		minIO-example.sln

ArgCodeTools/minIO-example

Folders and files

Latest commit

History

Repository files navigation

MinIO Example - Proyecto Personal

🚀 Setup

1. Levantar MinIO

2. Configurar MinIO

3. Ejecutar API

📋 Endpoints Principales

🧪 Para Probar

🐳 Docker

🧪 Pruebas

3. Crear bucket inicial

4. Ejecutar la API

📋 Endpoints Disponibles

🔽 Descargar / Consultar Imágenes

📤 Subir Imágenes

🔒 Endpoint Recomendado: /secure-url

🔍 Validación Completa: /validate

🧪 Ejemplos de Uso

Casos de Uso Principales

📤 Subir Imágenes

Endpoints con Verificación

Usando el archivo .http

Usando Swagger UI

⚙️ Configuración

Variables de entorno (opcional)

Configuración en appsettings.json

🐳 Comandos Docker Útiles

📁 Estructura del Proyecto

Características Principales

✅ URLs Seguras

🔍 Validación Robusta

📸 Gestión de Imágenes

🔄 Compatibilidad

🔧 Tecnologías Utilizadas

📚 Recursos Adicionales

🔐 Seguridad

🐛 Troubleshooting

MinIO no se conecta

Error de SSL

Bucket no existe

Imagen no encontrada

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

🔒 Endpoint Recomendado: `/secure-url`

🔍 Validación Completa: `/validate`

Packages