> For the complete documentation index, see [llms.txt](https://docs.opensoutheners.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opensoutheners.com/home/laravel-apiable/request-features/overview.md).

# Overview

Allow API consumers to filter, sort, include relationships, select fields, append accessors, and search your resources.

Laravel Apiable lets you expose a rich, controlled set of query capabilities to API consumers. Rather than building custom query logic per endpoint, you declare what is allowed and the package handles the rest — parsing, validating, and applying each parameter to the underlying Eloquent query.

## Available features

| Feature          | Query parameter                       | Documentation                                                      |
| ---------------- | ------------------------------------- | ------------------------------------------------------------------ |
| Filters          | `filter[attribute]=value`             | [Filters](/home/laravel-apiable/request-features/filters.md)       |
| Sorts            | `sort=attribute` or `sort=-attribute` | [Sorts](/home/laravel-apiable/request-features/sorts.md)           |
| Includes         | `include=relationship`                | [Includes](/home/laravel-apiable/request-features/includes.md)     |
| Sparse fieldsets | `fields[type]=col1,col2`              | [Fields](/home/laravel-apiable/request-features/fields.md)         |
| Appends          | `appends[type]=accessor`              | [Appends](/home/laravel-apiable/request-features/appends.md)       |
| Full-text search | `?q=term` or `?search=term`           | [Search](/home/laravel-apiable/request-features/search.md)         |
| Param validation | —                                     | [Validation](/home/laravel-apiable/request-features/validation.md) |

## Two approaches

All request features can be configured in two ways. Both produce identical behaviour — choose the style that fits your project.

### Using fluent methods on `JsonApiResponse`

Call the `allowing()` method with a mixed array of `Allowed*` instances, or use the dedicated per-feature methods (`allowFilter()`, `allowSort()`, etc.):

```php
use OpenSoutheners\LaravelApiable\Http\JsonApiResponse;
use OpenSoutheners\LaravelApiable\Http\AllowedFilter;
use OpenSoutheners\LaravelApiable\Http\AllowedSort;
use OpenSoutheners\LaravelApiable\Http\AllowedInclude;

public function index()
{
    return JsonApiResponse::from(Post::class)
        ->allowing([
            AllowedFilter::similar('title'),
            AllowedFilter::exact('author.name'),
            AllowedSort::make('created_at'),
            AllowedInclude::make('author'),
        ]);
}
```

You can mix any combination of `AllowedFilter`, `AllowedSort`, `AllowedInclude`, `AllowedFields`, `AllowedAppends`, and `AllowedSearchFilter` in the same `allowing()` call.

### Using PHP Attributes on controller methods or classes

Attributes are declared above your controller method (or above the class for shared configuration). They are resolved automatically when `JsonApiResponse` processes the request:

```php
use OpenSoutheners\LaravelApiable\Attributes\FilterQueryParam;
use OpenSoutheners\LaravelApiable\Attributes\SortQueryParam;
use OpenSoutheners\LaravelApiable\Attributes\IncludeQueryParam;
use OpenSoutheners\LaravelApiable\Http\AllowedFilter;
use OpenSoutheners\LaravelApiable\Http\AllowedSort;
use OpenSoutheners\LaravelApiable\Http\JsonApiResponse;

#[FilterQueryParam('title', AllowedFilter::SIMILAR)]
#[FilterQueryParam('author.name', AllowedFilter::EXACT)]
#[SortQueryParam('created_at')]
#[IncludeQueryParam('author')]
public function index(JsonApiResponse $response)
{
    return $response->using(Post::class);
}
```

{% hint style="info" %}
Every `*QueryParam` attribute accepts an optional `$description` string as its last parameter. This description is used by the `apiable:docs` command when generating API documentation. See [Generating Documentation](https://github.com/open-southeners/laravel-apiable/blob/main/docs/documentation/README.md) for details.
{% endhint %}

Attributes can be placed at the **class level** (applying to all methods) or at the **method level** (applying to that action only). Method-level attributes take precedence.

## Combining `allowing()` with individual methods

The `allowing()` method is a convenience wrapper. Underneath it calls the same individual methods, so you can mix both styles freely:

```php
return JsonApiResponse::from(Post::class)
    ->allowing([
        AllowedFilter::similar('title'),
        AllowedSort::make('created_at'),
    ])
    ->allowInclude('author')
    ->allowInclude('tags')
    ->allowSearch();
```

## Next steps

* [Filters](/home/laravel-apiable/request-features/filters.md) — filter by attribute, relationship, or query scope
* [Sorts](/home/laravel-apiable/request-features/sorts.md) — sort results ascending or descending
* [Includes](/home/laravel-apiable/request-features/includes.md) — eager-load relationships as compound documents
* [Fields](/home/laravel-apiable/request-features/fields.md) — select specific columns per resource type
* [Appends](/home/laravel-apiable/request-features/appends.md) — include computed model accessors
* [Search](/home/laravel-apiable/request-features/search.md) — full-text search via Laravel Scout
* [Validation](/home/laravel-apiable/request-features/validation.md) — reject unrecognised or invalid query parameters


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.opensoutheners.com/home/laravel-apiable/request-features/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.