Guía rápida API REST con Lumen

1. Creación del proyecto

Instala Lumen vía Composer (crea un directorio dwcs con los ficheros de Lumen):

composer create-project --prefer-dist laravel/lumen dwcs
cd dwcs

2. Levantar el servidor

Usa el servidor integrado de PHP:

php -S localhost:8000 -t public

Accede en: http://localhost:8000.

Si estamos levantando el servidor en otro equipo, debemos indicar la IP: http://192.168.56.80:8000, pero deberíamos ejecutar el siguiente comando para tener acceso desde un equipo externo:

php -S 0.0.0.0:8000 -t public

3. Configuración del .env

Copia el archivo de ejemplo y edítalo:

cp .env.example .env

Configura la conexión a la base de datos:

APP_NAME=MiAPI
APP_ENV=local
APP_KEY=base64:TU_CLAVE_AQUI
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=lumen
DB_USERNAME=root
DB_PASSWORD=abc123.

Si es necesario, genera la APP_KEY con:

php artisan key:generate

4. Levantar una base de datos MariaDB

Crea un fichero compose.yml con el siguiente contenido:

services:

  mariadb:
    image: mariadb:12
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: abc123.
      MYSQL_DATABASE: lumen
      MYSQL_USER: user
      MYSQL_PASSWORD: abc123.
    ports:
      - 3306:3306
    volumes:
      - mariadb_lumen:/var/lib/mysql

  phpmyadmin:
    image: phpmyadmin/phpmyadmin:5.2
    links:
      - mariadb
    environment:
      PMA_HOST: mariadb
      PMA_PORT: 3306
      PMA_ARBITRARY: 1
    restart: always
    ports:
      - 9000:80
    depends_on:
      - mariadb

volumes:
  mariadb_lumen:

Para levantar MariaDB, ejecuta:

docker compose up -d

Puedes acceder a un panel de administración phpMyAdmin a través de http://localhost:9000 (http://192.168.56.80:9000 si estamos levantando en un servidor remoto). Los datos de acceso son:

• Host: mariadb
• Username: root
• Password: abc123.

5. Migraciones

Crea una migración para, por ejemplo, una tabla productos:

php artisan make:migration create_productos_table

Edita el archivo generado en database/migrations/:

public function up()
{
    Schema::create('productos', function (Blueprint $table) {
        $table->id();
        $table->string('nombre');
        $table->decimal('precio', 8, 2);
        $table->timestamps();
    });
}

Ejecuta las migraciones:

php artisan migrate

6. Modelos — Habilitar Eloquent

Por defecto, Lumen tiene Eloquent desactivado. Debes habilitarlo en bootstrap/app.php:

// Descomenta esta línea
$app->withEloquent();

Luego crea el modelo en app/Models/Producto.php:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Producto extends Model
{
    protected $table = 'productos';

    protected $fillable = ['nombre', 'precio'];
}

El modelo se debe crear manualmente, no existe un comando de artisan.

7. Controladores

Crea el controlador en app/Http/Controllers/ProductoController.php:

<?php

namespace App\Http\Controllers;

use App\Models\Producto;
use Illuminate\Http\Request;

class ProductoController extends Controller
{
    // GET /productos
    public function index()
    {
        return response()->json(Producto::all());
    }

    // GET /productos/{id}
    public function show($id)
    {
        $producto = Producto::find($id);
        if (!$producto) {
            return response()->json(['error' => 'No encontrado'], 404);
        }
        return response()->json($producto);
    }

    // POST /productos
    public function store(Request $request)
    {
        $validated = $this->validate($request, [
            'nombre' => 'required|string',
            'precio' => 'required|numeric',
        ]);

        $producto = Producto::create($validated));
        return response()->json($producto, 201);
    }

    // PUT /productos/{id}
    public function update(Request $request, $id)
    {
        $producto = Producto::find($id);
        if (!$producto) {
            return response()->json(['error' => 'No encontrado'], 404);
        }

        $validated = $this->validate($request, [
            'nombre' => 'required|string',
            'precio' => 'required|numeric',
        ]);

        $producto->update($request->only($validated));
        return response()->json($producto);
    }

    // DELETE /productos/{id}
    public function destroy($id)
    {
        $producto = Producto::find($id);
        if (!$producto) {
            return response()->json(['error' => 'No encontrado'], 404);
        }
        $producto->delete();
        return response()->json(['message' => 'Eliminado correctamente']);
    }
}

El controlador se debe crear manualmente, no existe un comando de artisan. Puedes tomar como referencia ExampleController.php.

8. Routing

Define las rutas en routes/web.php:

$router->get('productos',         'ProductoController@index');
$router->get('productos/{id}',    'ProductoController@show');
$router->post('productos',        'ProductoController@store');
$router->put('productos/{id}',    'ProductoController@update');
$router->delete('productos/{id}', 'ProductoController@destroy');

9. Peticiones con cURL

Podemos usar herramientas como Postman, Apidog o Insomnia para probar los endpoints de forma visual. Por otra banda, podemos hacerlo a través de la línea de comandos con cURL.

Listar todos los productos

curl http://localhost:8000/api/productos

Obtener un producto por ID

curl http://localhost:8000/api/productos/1

Crear un producto (POST)

curl -X POST http://localhost:8000/api/productos \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Laptop", "precio": 999.99}'

Actualizar un producto (PUT)

curl -X PUT http://localhost:8000/api/productos/1 \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Laptop Pro", "precio": 1299.99}'

Eliminar un producto (DELETE)

curl -X DELETE http://localhost:8000/api/productos/1