Cuando trabajas con APIs versionadas, cada versión puede requerir campos distintos, nombres diferentes y relaciones específicas. Comprender cómo configurar un recurso (resource) para una nueva versión te permite atender las necesidades de distintos clientes o aplicaciones sin romper la compatibilidad con versiones anteriores.
¿Cómo se configura un recurso para la versión dos del API?
El punto de partida es el controlador de la versión dos, donde ya se cuenta con las rutas y el controlador creados previamente. Desde el método show del controlador se retorna una nueva instancia del recurso de post, siguiendo el mismo esquema usado en la versión uno [01:02].
La diferencia clave está en el archivo del recurso ubicado en app/Http/Resources/V2. Aquí se define un array con los campos que el cliente de esta versión necesita:
- ID: se mantiene igual.
- post_name: en lugar de llamarse "título", el campo se renombra a
post_name, aunque internamente sigue siendo el título del post.
- Contenido directo: a diferencia de la versión uno que enviaba el extracto, ahora se entrega el contenido completo.
- Autor: se incluye como un sub-arreglo con nombre y email del usuario relacionado.
- Fecha de creación: se utiliza un campo virtual previamente desarrollado que formatea las fechas de manera más clara.
Esta flexibilidad es precisamente lo que hace valioso el versionado de APIs: cada versión puede exponer los datos con la estructura que su consumidor requiere.
¿Por qué se separan los campos de la izquierda y la derecha?
Una forma práctica de entender la responsabilidad en un API es pensar en dos lados [02:30]. Los campos de la izquierda son los nombres que el desarrollador frontend o la aplicación consumidora solicita. Los campos de la derecha son los valores reales que tú, como programador del API, mapeas desde la base de datos o el modelo. Tú controlas qué dato se entrega; el consumidor define cómo quiere recibirlo.
¿Cómo se configura la relación belongs to para el autor?
Al intentar acceder a this->user sin configurar la relación en el modelo, Laravel lanza un error indicando que user no existe [03:15]. La solución es definir en el modelo Post que un post pertenece a un usuario mediante el método belongsTo:
php
public function user()
{
return $this->belongsTo(User::class);
}
Con esta relación establecida, dentro del recurso se puede acceder a $this->user->name y $this->user->email para construir el objeto autor que se retorna en la respuesta JSON.
¿Cómo se verifica el funcionamiento de ambas versiones?
Desde Postman se pueden probar ambas versiones para confirmar que cada una responde con su estructura propia [03:50].
- Versión uno (
/api/v1/posts/1): retorna título, slug, extracto y contenido. Simula una aplicación antigua conectada a los recursos originales.
- Versión dos (
/api/v2/posts/1): retorna el mismo registro pero con campos diferentes: id, post_name, un objeto author con nombre y email, y la fecha de creación formateada.
Ambas versiones coexisten sin conflicto. Esto significa que las aplicaciones existentes siguen funcionando con la versión uno, mientras que nuevos dispositivos o software se conectan a la versión dos con la estructura actualizada.
El concepto de recurso en Laravel (API Resource) actúa como una capa de transformación entre el modelo y la respuesta JSON. Cada versión del recurso define su propio array de salida, lo que permite renombrar campos, incluir relaciones y agregar campos virtuales sin modificar el modelo ni la base de datos.
Si estás implementando versionado en tu propio proyecto, experimenta creando una tercera versión con campos completamente distintos y comparte cómo organizas tus recursos.
