Adding api name to routing registration

[omaresmael]

I was trying to structure my api to be versioned route files and I managed to do it like so

Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php', //registering the main api route file
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        apiPrefix: 'api', // grouping all the api routes with prefix of api/

    )->create();

//api.php
Route::prefix('v1')->group(
    base_path('routes/api/v1/routes.php') 
);
Route::prefix('v2')->group(
    base_path('routes/api/v2/routes.php') 
);
Route::prefix('v3')->group(
    base_path('routes/api/v3/routes.php') 
);

The issue

The issue comes with the group-naming of the routes inside these files. to group name them, you have to repeat the name prefix for every version

//api.php
Route::prefix('v1')->->name('api:v1:')->group(
    base_path('routes/api/v1/routes.php') 
);
Route::prefix('v2')->->name('api:v2:')->group(
    base_path('routes/api/v2/routes.php') 
);
Route::prefix('v3')->->name('api:v3:')->group(
    base_path('routes/api/v3/routes.php') 
);

The solution

While you can name group inside the api file to prevent duplication

Route::name('api:')->group(function (){
    Route::prefix('v1')->name('v1:')->group(
        base_path('routes/api/v1/routes.php')
    );
    Route::prefix('v2')->name('v2:')->group(
        base_path('routes/api/v2/routes.php')
    );
    Route::prefix('v3')->name('v3:')->group(
        base_path('routes/api/v3/routes.php')
    );
});

I think its more convenient to register it once like the api prefix

Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php', //registering the main api route file
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        apiPrefix: 'api', // grouping all the api routes with prefix of api/
        apiName: 'api:'

    )->create();

//api.php
Route::prefix('v1')->->name('v1:')->group(
    base_path('routes/api/v1/routes.php') 
);
Route::prefix('v2')->->name('v2:')->group(
    base_path('routes/api/v2/routes.php') 
);
Route::prefix('v3')->->name('v3:')->group(
    base_path('routes/api/v3/routes.php') 
);

I've implemented the solution locally and it worked as expected, let me know please if you think I should submit a pr for it
Thank you ❤️

[shaedrich]

What about allowing api to take an array of paths?

[omaresmael]

How would you set the api name for the array of paths?

[shaedrich]

Either in the respective route file like this, eliminating the need for an api.php entirely:

Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: [
            __DIR__.'/../routes/api/v1/routes.php',
            __DIR__.'/../routes/api/v2/routes.php',
            __DIR__.'/../routes/api/v3/routes.php',
        ],
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        apiPrefix: 'api', // grouping all the api routes with prefix of api/

    )->create();

//api/v1/routes.php
Route::prefix('v1')->group(
    // your v1 routes
);

//api/v2/routes.php
Route::prefix('v2')->group(
    // your v2 routes
);

or instead of it being string[], keys can be used as array<string, string>:

Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: [
            'v1' => __DIR__.'/../routes/api/v1/routes.php',
            'v2' => __DIR__.'/../routes/api/v2/routes.php',
            'v3' => __DIR__.'/../routes/api/v3/routes.php',
        ],
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        apiPrefix: 'api', // grouping all the api routes with prefix of api/

    )->create();

[shaedrich]

It looks a bit like the issue is whether the name should be nested or not. This could be solved by starting the name with a colon to indicated that it is relative to the parent name.

What I don't particularly like about parameters like apiPrefix and apiName, is that they are related to other parameters and therefore dependent on them. In other words: They don't have anything to do with the other function parameters and therefore, they are bloating the function signature and don't really belong there in the first place. They would need to be passed to api directly instead.