description: Append computed model accessors to your JSON:API resource attributes.

Appends

Appends allow API consumers to request computed model accessors alongside the standard resource attributes. Unlike sparse fieldsets, appends do not affect the database SELECT — they are applied to the loaded model instances after the query completes.

URL format

GET /posts?appends[post]=is_featured
GET /posts?appends[post]=is_featured,reading_time&appends[user]=avatar_url

The key inside appends[] is the JSON:API resource type. The value is a comma-separated list of accessor names.

AllowedAppends::make()

AllowedAppends::make() takes a resource type and an array (or string) of accessor names:

use OpenSoutheners\LaravelApiable\Http\AllowedAppends;

AllowedAppends::make('post', ['is_featured', 'reading_time'])
AllowedAppends::make('user', ['avatar_url'])

Instead of a string resource type, you can pass the model class directly — the package resolves the type from your resource_type_map config:

use App\Models\User;

AllowedAppends::make(User::class, ['avatar_url'])

Allowing appends

{% tabs %} {% tab title="Using methods" %} Pass AllowedAppends instances to allowing(), or call allowAppends() directly:

use OpenSoutheners\LaravelApiable\Http\JsonApiResponse;
use OpenSoutheners\LaravelApiable\Http\AllowedAppends;
use App\Models\User;

public function index()
{
    return JsonApiResponse::from(Post::class)
        ->allowing([
            AllowedAppends::make('post', ['is_featured', 'reading_time']),
            AllowedAppends::make('user', ['avatar_url']),
        ]);
}

Using allowAppends() directly with a string type:

return JsonApiResponse::from(Post::class)
    ->allowAppends('post', ['is_featured', 'reading_time'])
    ->allowAppends('user', ['avatar_url']);

Using a model class for the type argument:

return JsonApiResponse::from(Post::class)
    ->allowAppends(User::class, ['avatar_url']);

Shorthand — pass an array as the first argument to target the main resource type:

return JsonApiResponse::from(Post::class)
    ->allowAppends(['is_featured']);

{% endtab %}

{% tab title="Using attributes" %}

use OpenSoutheners\LaravelApiable\Attributes\AppendsQueryParam;
use OpenSoutheners\LaravelApiable\Http\JsonApiResponse;
use App\Models\User;

#[AppendsQueryParam('post', ['is_featured', 'reading_time'])]
#[AppendsQueryParam(User::class, ['avatar_url'])]
public function index(JsonApiResponse $response)
{
    return $response->using(Post::class);
}

AppendsQueryParam accepts: type (string resource type or model class-string), attributes (array of accessor names), and description. {% endtab %} {% endtabs %}

Fields vs. appends

Use allowFields() for real database columns when you want to reduce data transfer. Use allowAppends() for PHP-computed values (accessors defined with Attribute::make() or get*Attribute() methods) that have no corresponding database column.

Forcing appends unconditionally

If you want to always append specific accessors regardless of what the consumer requests, use forceAppend() on JsonApiResponse. See the JsonApiResponse documentation for details.