La estructura que ya conoces

Una aplicación de Laravel 13 es pequeña cuando es nueva. Las carpetas aparecen a medida que le pides cosas a Artisan, y cada una tiene un solo trabajo:

app/Http/Controllers/   make:controller   HTTP entra y sale
app/Http/Requests/      make:request      validación
app/Http/Resources/     make:resource     salida JSON
app/Http/Middleware/    make:middleware   el pipeline HTTP
app/Jobs/               make:job          trabajo para la cola
app/Providers/          make:provider     el contenedor
routes/api.php                            los endpoints
tests/Feature/          make:test         tests completos

Esta API añade dos carpetas que ningún comando de Artisan crea:

app/Services/License/   la integración con Statamic
app/Facades/            el nombre que usa la aplicación

El Capítulo 3 explica las dos. Todo lo demás se queda donde un desarrollador de Laravel espera encontrarlo. Cuando alguien nuevo llega al equipo y abre el proyecto, debería pensar «esto ya lo he visto». Esa reacción vale más que cualquier estructura que pudieras inventar.

El endpoint que Laravel te regala

Antes de escribir nada, mira lo que ya hay. Abre bootstrap/app.php:

->withRouting(
    api: __DIR__.'/../routes/api.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
)

Esa línea health es una comprobación de salud que ya funciona. GET /up devuelve un 200 cuando la aplicación arranca y un 500 cuando no, que es lo que un balanceador de carga necesita saber. No la escribiste tú y no la mantienes tú. El Capítulo 13 la amplía para comprobar la base de datos y la caché. (Documentación de Laravel: Deployment › The Health Route.)

Conviértelo en costumbre: antes de construir algo, comprueba si Laravel ya lo trae.

Tu primer endpoint

El primer endpoint de verdad lista licencias. Esta es la versión que se escribe en cinco minutos:

// routes/api.php
Route::get('/licenses', function () {
    $token = config('services.statamic.token');

    return Http::withToken($token)
        ->get('https://statamic.com/api/v1/sites')
        ->json('data');
});

Funciona. Podrías enseñarla hoy en una demo. También es una lista de problemas a la espera de un segundo endpoint:

• Devuelve todo lo que devuelva Statamic. Si mañana el proveedor añade un campo, tu API lo expone mañana. Tus consumidores quedan acoplados a una empresa de la que nunca han oído hablar.
• Nada comprueba lo que llegó. Una clave ausente o un null viajan directos hasta el cliente.
• El proveedor está soldado a la ruta. La URL, el token y la llamada HTTP están en el único lugar que solo debería saber de HTTP.
• No se puede probar sin llamar a Statamic o simularlo a mano en cada test.
• El siguiente endpoint la copiará. Y el tercero la copiará de un modo ligeramente distinto.

Nada de esto hace que la versión rápida esté mal. La convierte en un prototipo. Este es el mismo endpoint tal como los construye el resto del libro:

// routes/api.php
Route::apiResource('licenses', LicenseController::class)
    ->only(['index', 'store', 'destroy']);

// app/Http/Controllers/LicenseController.php
public function index(): AnonymousResourceCollection
{
    return LicenseResource::collection(Licenses::all());
}

Una línea de rutas declara los tres endpoints con los nombres y los verbos que todo desarrollador de Laravel ya conoce: GET /licenses es index, POST /licenses es store, DELETE /licenses/{license} es destroy. (Documentación de Laravel: Controllers › API Resource Routes.)

El método del controlador también ocupa una línea, y cada parte responde a uno de los problemas de arriba. Licenses::all() esconde al proveedor detrás de una interfaz y devuelve objetos tipados, de modo que nada mal formado pasa de ahí. LicenseResource decide qué campos salen de la API, así que la forma del proveedor nunca se filtra. El controlador sabe de HTTP y de nada más.

Aquí no hay magia, solo unos cuantos archivos más. Los dos capítulos siguientes construyen cada uno de ellos.

Principios para entregar rápido

Cinco principios recorren el resto del libro.

Convención antes que configuración. Las convenciones de Laravel son el destilado de miles de aplicaciones en producción. Haz las cosas a la manera de Laravel por defecto, y sal de ella solo cuando tengas una razón concreta que puedas poner por escrito. Este libro sale de ella en unos pocos lugares, y cada vez explica por qué.

Consistencia antes que novedad. Cada endpoint debería parecerse al anterior. La validación en un FormRequest, la salida a través de un Resource, el proveedor detrás de una interfaz. Cuando algo tiene que cambiar, cambia en un solo lugar.

Tipos en las fronteras. Usa declaraciones de tipo y tipos de retorno, y ejecuta el análisis estático a un nivel que tu equipo vaya a mantener en verde. Los lugares que más importan son los bordes, donde los datos llegan de un cliente o de un proveedor. Una vez que un valor tiene tipo, el resto del código puede fiarse de él.

Falla pronto. Valida la entrada antes de que se ejecute el controlador. Rechaza una respuesta mal formada del proveedor allí donde llega, en lugar de dejar que un valor incorrecto viaje hacia dentro y falle lejos de su causa.

Prueba mientras construyes. No después, ni algún día. Un test escrito junto con el endpoint atrapa el error cuando todavía recuerdas lo que querías hacer.

La seguridad también pertenece a esa lista, y recorre el libro entero: la autenticación en el Capítulo 4, la autorización sobre registros en el Capítulo 5, el pipeline de la petición en el Capítulo 6 y una revisión de todo ello en el Capítulo 19.

Resumen del capítulo 1

• La License API gestiona licencias que viven en un proveedor externo. No tiene una tabla propia para ellas.
• Empieza con install:api y deja que Artisan cree las carpetas.
• Antes de construir algo, comprueba si Laravel ya lo trae. La ruta de salud es el primer ejemplo.
• Un closure de ruta que llama al proveedor es un prototipo. Una ruta de recurso, un controlador delgado, un Resource y una facade son la versión que perdura.
• Convención, consistencia, tipos en las fronteras, fallar pronto y tests escritos junto con el código.