HATEOAS

Son una manera de mejorar la navegación y la información para la API. Por medio de HATEOAS se pueden generar enlaces entre diferentes recursos de la API, por ejemplo, si cada que se vaya a retornar una instancia de Buyer se pueden incluir enlaces a si mismo y demás modelos relacionados.

HATEOAS es un acrónimo de Hypermedia As The Engine Of Application State (hipermedia como motor del estado de la aplicación). Significa algo así como que, dado un punto de entrada genérico de nuestra API REST, podemos ser capaces de descubrir sus recursos basándonos únicamente en las respuestas del servidor.

https://www.adictosaltrabajo.com/tutoriales/spring-hateoas/#03

Dentro de las buenas prácticas de HATEOAS se tiene que la más común es agregar a cada respuesta de la API, un elemento llamado links que incluya un enlace a si mismo y un enlace para cada recurso al que este relacionado.

• Implementación de HATEOAS para instancias de cada modelo

Se facilita gracias a los transformadores que permiten añadir nuevos elementos a los objetos retonados

public function transform(Category $category)
{
    return [
        'identifier' => (int) $category->id,
        'title' => (string) $category->name,
        'details' => (string) $category->description,
        'createdAt' => (string) $category->created_at,
        'updatedAt' => (string) $category->updated_at,
        'deletedAt' => isset($category->deleted_at) ? (string) $category->deleted_at : null,
        'links' => [
            [
                'rel' => 'self',
                'href' => route('categories.show', $category->id),
            ],
            [
                'rel' => 'category.buyers',
                'href' => route('categories.buyers.index', $category->id),
            ],
            [
                'rel' => 'category.products',
                'href' => route('categories.products.index', $category->id),
            ],
            [
                'rel' => 'category.sellers',
                'href' => route('categories.sellers.index', $category->id),
            ],
            [
                'rel' => 'category.transactions',
                'href' => route('categories.transactions.index', $category->id),
            ],
        ]
    ];
}

En caso de tener llaves foráneas, como seller_id en Product, el link se incluye

public function transform(Product $product)
{
    return [
        'identifier' => (int) $product->id,
        'name' => (string) $product->name,
        'details' => (string) $product->description,
        'available' => (int) $product->quantity,
        'status' => (string) $product->status,
        'image' => url("img/{$product->image}"),
        'seller' => (int) $product->seller_id,
        'createdAt' => (string) $product->created_at,
        'updatedAt' => (string) $product->updated_at,
        'deletedAt' => isset($product->deleted_at) ? (string) $product->deleted_at : null,
        'links' => [
            [
                'rel' => 'self',
                'href' => route('products.show', $product->id),
            ],
            [
                'rel' => 'product.buyers',
                'href' => route('products.buyers.index', $product->id),
            ],
            [
                'rel' => 'product.categories',
                'href' => route('products.categories.index', $product->id),
            ],
            [
                'rel' => 'product.transactions',
                'href' => route('products.transactions.index', $product->id),
            ],
            [
                'rel' => 'seller',
                'href' => route('sellers.show', $product->seller_id),
            ],
        ],
    ];
}