9. Subida de Archivos y Multimedia en APIs: multipart/form-data y Storage
Recibe avatares o documentos con validaciones de tipo MIME y peso máximo, almacenándolos con el disco public o Amazon S3 y devolviendo URLs públicas.
Subida de Archivos en Peticiones de API
Cuando un cliente necesita adjuntar una imagen de producto, un avatar de usuario o un documento PDF a la API, no puede enviar un payload application/json convencional. La petición debe codificarse como multipart/form-data.
Validación de Archivos con la Regla File
Laravel incluye un objeto de validación robusto Illuminate\Validation\Rules\File que permite verificar dimensiones de imágenes, extensiones permitidas y tamaño máximo en kilobytes:
'avatar' => [
'required',
File::image()
->types(['jpg', 'jpeg', 'png', 'webp'])
->max(2 * 1024), // Máximo 2 MB
],
Almacenamiento con Storage::disk('public')
Nunca guardes archivos directamente en la carpeta public/. Utiliza la abstracción de discos de Laravel:
- Los archivos se guardan en
storage/app/public/avatares. - Se ejecuta el enlace simbólico
php artisan storage:link. - En el API Resource devuelves la URL pública generada con
Storage::url($ruta).
⚡ Controlador API para Subir Imagen y Retornar URL Pública
Ejemplo completo de subida de imagen de producto con Storage y Resource:
<?php
namespace App\Http\Controllers\Api\V1;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Storage;
use Illuminate\Validation\Rules\File;
class AvatarUploadController extends Controller
{
/**
* POST /api/v1/perfil/avatar (multipart/form-data)
*/
public function subirAvatar(Request $request): JsonResponse
{
$request->validate([
'avatar' => [
'required',
File::image()
->types(['jpg', 'png', 'webp'])
->max(2048), // 2MB
],
]);
$usuario = $request->user();
// 1. Eliminar avatar previo si existía para no acumular basura en el VPS
if ($usuario->avatar_path && Storage::disk('public')->exists($usuario->avatar_path)) {
Storage::disk('public')->delete($usuario->avatar_path);
}
// 2. Guardar el nuevo archivo con nombre aleatorio único en storage/app/public/avatares
$ruta = $request->file('avatar')->store('avatares', 'public');
// 3. Actualizar el registro del usuario
$usuario->update(['avatar_path' => $ruta]);
// 4. Retornar URL pública absoluta
return response()->json([
'status' => 'success',
'mensaje' => 'Avatar actualizado exitosamente',
'avatar_url' => Storage::disk('public')->url($ruta),
], 200);
}
}
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Qué comando de Artisan es necesario ejecutar una vez para que los archivos guardados en el disco "public" sean accesibles públicamente desde la web?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar APIs RESTful con Laravel, Resources & Sanctum y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.