Skip to main content

​
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.

​
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.

​
Basic Security Example

To make a route private, you add a RouteAuthorization to the route’s constructor: 
use apivalk\apivalk\Router\Route;
use apivalk\apivalk\Security\RouteAuthorization;

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

​
Public and Optional Security

  • Public Route: If no security requirements are provided (default), the route is public.
  • Optional Security: Currently, if you want a route to be public but also optionally use identity information if provided, you leave RouteAuthorization as null. The SecurityMiddleware only enforces authorization if a RouteAuthorization is defined.
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. The framework’s automated discovery system then picks up these definitions and registers them with the router.