UUID primary keys cause IRI generation failure in Laravel

[SofianeLasri]

API Platform version(s) affected: 4.1.20

Description
When using UUID as the primary key for Eloquent models with API Platform Laravel, the IriConverter fails to generate proper IRIs for individual items in collections. This results in a InvalidArgumentException: Unable to generate an IRI for the item of type 'App\Models\Building' error when trying to serialize collections in JSON:API format.

The issue occurs because API Platform generates malformed route names (_api_/api/buildings{._format}_get) that don't match the actual Laravel routes and don't include the UUID parameter.

How to reproduce

1. Create a Laravel model with UUID as primary key:

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Delete;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/buildings',
            name: 'api_buildings_get_collection'
        ),
        new Get(
            uriTemplate: '/buildings/{uuid}',
            name: 'api_buildings_get_item'
        ),
        new Post(
            uriTemplate: '/buildings',
            name: 'api_buildings_post'
        ),
        new Put(
            uriTemplate: '/buildings/{uuid}',
            name: 'api_buildings_put'
        ),
        new Delete(
            uriTemplate: '/buildings/{uuid}',
            name: 'api_buildings_delete'
        )
    ],
    normalizationContext: ['groups' => ['building:read']],
    denormalizationContext: ['groups' => ['building:write']],
    paginationEnabled: true
)]
class Building extends Model
{
    protected $primaryKey = 'uuid';
    protected $keyType = 'string';
    public $incrementing = false;
    
    protected static function boot()
    {
        parent::boot();
        static::creating(function ($model) {
            if (!$model->uuid) {
                $model->uuid = (string) Str::uuid();
            }
        });
    }
}

2. Create a migration with UUID primary key:

Schema::create('buildings', function (Blueprint $table) {
    $table->uuid('uuid')->primary();
    $table->string('name');
    $table->uuid('user_uuid');
    $table->timestamps();
});

3. Configure API Platform (config/api-platform.php):

return [
    'formats' => [
        'jsonapi' => ['application/vnd.api+json'],
    ],
    'defaults' => [
        'route_prefix' => '/api',
    ],
];

4. Make a request to the collection endpoint:

// Test case
public function test_it_lists_buildings(): void
{
    Building::factory()->count(3)->create();
    
    $response = $this->get('/api/buildings', [
        'Accept' => 'application/vnd.api+json',
    ]);
    
    $response->assertOk(); // Fails with IRI generation error
}

Error Output:

InvalidArgumentException: Unable to generate an IRI for the item of type "App\Models\Building"

Stack trace:
#0 vendor/api-platform/laravel/Routing/IriConverter.php(182): Unable to generate an IRI for the item of type "App\Models\Building"
api-platform/api-platform#1 vendor/api-platform/laravel/Routing/IriConverter.php(149): ApiPlatform\Laravel\Routing\IriConverter->generateRoute()
api-platform/api-platform#2 vendor/api-platform/jsonapi/Serializer/ItemNormalizer.php(100): ApiPlatform\Laravel\Routing\IriConverter->getIriFromResource()

Debug logs from IriConverter:

[IriConverter] Generating route:
- routeName: "_api_/api/buildings{._format}_get"
- identifiers: ["uuid" => "550e8400-e29b-41d4-a716-446655440000"]
- operation_class: "ApiPlatform\Metadata\Get"
- operation_name: "_api_/api/buildings{._format}_get"

Possible Solution
The issue appears to be in IriConverter::getIriFromResource() where it creates a new Get operation without proper configuration:

// Line 119-125 in IriConverter.php
if (!$operation) {
    $operation = (new Get())->withClass($resourceClass);
}

This new operation doesn't have the correct route name or URI template. The IriConverter should:

1. Use the explicitly defined operation names from the ApiResource attribute
2. Properly detect and handle UUID identifiers
3. Generate route names that match Laravel's routing conventions

A potential fix would be to ensure the operation metadata is properly loaded from the resource metadata factory before attempting to generate IRIs.

Additional Context

• Laravel version: 12.x
• PHP version: 8.4+
• Database: MariaDB with UUID columns
• Authentication: Laravel Sanctum

The error occurs specifically when the JSON:API serializer tries to generate the @id field for each item in a collection. Individual item fetches may work if accessed directly, but collections fail during serialization.

This bug prevents any Laravel application using UUIDs as primary keys from working properly with API Platform, which is a significant limitation since UUIDs are commonly used in modern applications for distributed systems and better security.

Workarounds attempted (all failed):

• Defining explicit operations with names and uriTemplates
• Using custom State Providers
• Changing route prefix configurations
• Testing with different output formats (JSON:API, HAL+JSON)