Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.apivalk.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Properties

A Route instance contains the following information:
  • URL: The path template for the endpoint (e.g., /api/v1/users/{id}).
  • Method: An implementation of MethodInterface representing the allowed HTTP verb (GET, POST, etc.).
  • Description: An optional human-readable description used for documentation (OpenAPI).
  • Tags: A collection of TagObject instances used for grouping endpoints in documentation.
  • Security Requirements: A RouteAuthorization instance defining the authentication and authorization needed for the route.
  • Rate Limit: An optional RateLimitInterface implementation defining the rate limiting rules for the endpoint.
  • Sorting: A collection of Sort instances defining allowed sorting fields for the endpoint.
  • Pagination: A Pagination instance defining the pagination strategy (Page, Offset, or Cursor).
  • Filtering: A collection of FilterInterface instances defining allowed filtering fields for the endpoint.

​
Path Parameters

Routes support dynamic path parameters using the {parameterName} syntax. For example: 
Route::get('/users/{id}/profile');
These parameters are automatically identified and converted into capture groups in the internal regex generation logic.

​
Security and Authorization

Security requirements are defined on a per-route basis using the RouteAuthorization object. This allows you to specify which authentication scheme (e.g., Bearer, OAuth2) is required and what granular scopes and permissions the user must have.

​
Public Route

If no RouteAuthorization is provided (default), the route is fully public. Anyone can access it. 
Route::get('/about')->description('About page');

​
Authenticated Route (No Specific Scopes)

To require authentication without enforcing specific scopes or permissions, pass only the security scheme name. The SecurityMiddleware will reject anonymous users with a 401 Unauthorized but allow any authenticated identity through. 
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Security\RouteAuthorization;

Route::get('/me/profile')
    ->description('Get my profile')
    ->routeAuthorization(new RouteAuthorization('BearerAuth'));

​
Scoped Route (Specific Scopes and Permissions)

To require both authentication and specific scopes/permissions: 
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Security\RouteAuthorization;

Route::post('/orders')
    ->description('Create order')
    ->routeAuthorization(
        new RouteAuthorization('apiKey', ['accounting:orders'], ['accounting:orders:create'])
    );

​
Optional Security (Public with Identity)

If you want a route to be public but optionally use identity information when a token is provided, leave RouteAuthorization as null. The AuthenticationMiddleware will still populate the identity if a valid token is present, so you can check $request->getAuthIdentity()->isAuthenticated() in your controller. For more details on how the security system works, check the Security Overview.

​
Integration with Documentation

The Route class implements JsonSerializable, allowing it to be easily exported for OpenAPI (Swagger) generation. It includes helper methods for:
  • jsonSerialize(): Converts the route and its metadata into a format suitable for JSON export.
  • static byJson(string $json): Hydrates a Route object from a JSON string, which is used when loading routes from the router cache.

​
Usage in Controllers

In an Apivalk application, you typically don’t instantiate Route objects manually. Instead, you define them in your controller’s static getRoute() method: 
public static function getRoute(): Route
{
    return Route::get('/v1/hello-world')
                  ->description('A simple hello world endpoint')
                  ->tag(new TagObject('Greeting', 'Endpoints for saying hello'));
}

​
Rate Limiting

You can add rate limiting to a route by providing a rate limit object as the last argument to the Route constructor: 
use apivalk\apivalk\Router\RateLimit\IpRateLimit;

public static function getRoute(): Route
{
    return new Route::get('/v1/sensitive-data')
                      ->description('Access sensitive data')
                      ->rateLimit(new IpRateLimit('sensitive_access', 5, 60));
}
For more details on available rate limiting strategies, see the Rate Limit documentation.

​
Sorting

You can define which fields are allowed for sorting by using the sorting() method. This takes an array of Sort objects: 
use apivalk\apivalk\Router\Route\Sort\Sort;

public static function getRoute(): Route
{
    return Route::get('/v1/users')
                  ->description('List users')
                  ->sorting([
                      Sort::asc('id'),
                      Sort::desc('created_at')
                  ]);
}
The sorting() method also defines the default sorting for the route. If a user does not provide an order_by query parameter, the sorting() bag on the request object will be automatically populated with these defined values.

​
Pagination

You can enable pagination for a route using the pagination() method. This takes a Pagination object: 
use apivalk\apivalk\Router\Route\Pagination\Pagination;

public static function getRoute(): Route
{
    return Route::get('/v1/users')
                  ->description('List users')
                  ->pagination(Pagination::page()->setMaxLimit(100));
}
When pagination is enabled, the framework automatically handles the page, limit, offset, or cursor query parameters and includes them in the OpenAPI documentation. See the Pagination guide for more details.

​
Resource Routes

For CRUD endpoints against an AbstractResource, use Route::resource() to build a route pre-configured for one of the five resource modes. It derives the URL, HTTP method, and default configuration from the resource: 
use apivalk\apivalk\Resource\AbstractResource;
use apivalk\apivalk\Router\Route\Route;
use App\Resource\AnimalResource;

public static function getRoute(): Route
{
    return Route::resource(new AnimalResource(), AbstractResource::MODE_LIST);
}
In practice you won’t call Route::resource() yourself — AbstractResourceController::getRoute() does it for you. See Resources.

​
Filtering

You can define which fields are allowed for filtering by using the filtering() method. This takes an array of FilterInterface instances: 
use apivalk\apivalk\Router\Route\Filter\StringFilter;
use apivalk\apivalk\Router\Route\Filter\EnumFilter;
use apivalk\apivalk\Router\Route\Filter\DateFilter;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Documentation\Property\EnumProperty;
use apivalk\apivalk\Documentation\Property\DateProperty;

public static function getRoute(): Route
{
    return Route::get('/v1/users')
                  ->description('List users')
                  ->filtering([
                      EnumFilter::equals(new EnumProperty('status', 'Filter by status', ['active', 'inactive'])),
                      StringFilter::in(new StringProperty('type', 'Filter by type (in)')),
                      DateFilter::greaterThan(new DateProperty('created_at', 'Filter by creation date (greater than)'))
                  ]);
}
The filtering() method also defines the allowed filters for the route. Only configured filters will be automatically resolved from the query string and documented in OpenAPI. See the Filtering guide for more details.