Configuration

Configuration

Complete reference for all configuration options in config/apiroute.php.

---

Publish Configuration

php artisan vendor:publish --tag="apiroute-config"

---

API Versions (v2.0+)

Define your API versions directly in configuration. This is the recommended approach as it ensures versions are properly registered on every application boot, including between tests.

'versions' => [
    'v1' => [
        'routes' => base_path('routes/api/v1.php'),
        'middleware' => ['auth:sanctum'],
        'status' => 'deprecated',
        'deprecated_at' => '2025-06-01',
        'sunset_at' => '2025-12-01',
        'successor' => 'v2',
        'documentation' => 'https://docs.myapp.com/api/v1',
        'rate_limit' => 100,
    ],
    'v2' => [
        'routes' => base_path('routes/api/v2.php'),
        'middleware' => ['auth:sanctum'],
        'status' => 'active',
        'documentation' => 'https://docs.myapp.com/api/v2',
        'rate_limit' => 1000,
    ],
],

Version Options

Option	Type	Default	Description
routes	string	required	Path to route file
middleware	array	[]	Additional middleware
status	string	active	active, beta, deprecated, sunset
deprecated_at	string|null	null	Deprecation date (Y-m-d)
sunset_at	string|null	null	Sunset date (Y-m-d)
successor	string|null	null	Successor version name
documentation	string|null	null	Documentation URL
rate_limit	int|null	null	Requests per minute

See Version Declaration for detailed examples.

---

Detection Strategy

How the API version should be detected from incoming requests.

'strategy' => env('API_VERSION_STRATEGY', 'uri'),

Value	Description
uri	Version in URL path (default): /api/v1/users
header	Version in HTTP header: X-API-Version: 1
query	Version in query parameter: ?api_version=1
accept	Version in Accept header: application/vnd.api.v1+json

See Detection Strategies for detailed information.

---

Strategy Configuration

Customize each detection strategy:

URI Strategy

'strategies' => [
    'uri' => [
        'prefix' => 'api',           // URL prefix
        'pattern' => 'v{version}',   // Version pattern (v1, v2, etc.)
    ],
],

Examples:

• Default: /api/v1/users
• Custom prefix 'prefix' => 'service': /service/v1/users

Header Strategy

'strategies' => [
    'header' => [
        'name' => 'X-API-Version',   // Header name
    ],
],

Usage:

GET /api/users
X-API-Version: 2

Query Strategy

'strategies' => [
    'query' => [
        'parameter' => 'api_version', // Query parameter name
    ],
],

Usage:

GET /api/users?api_version=2

Accept Strategy

'strategies' => [
    'accept' => [
        'pattern' => 'application/vnd.{vendor}.{version}+json',
        'vendor' => env('API_VENDOR', 'api'),
    ],
],

Usage:

GET /api/users
Accept: application/vnd.api.v2+json

---

Default Version

Version to use when none is specified in the request.

'default_version' => env('API_DEFAULT_VERSION', 'latest'),

Value	Description
latest	Use the most recent non-beta version
v1, v2, etc.	Use a specific version

---

Fallback Behavior

When a route doesn't exist in the requested version, should we fallback to a previous version?

'fallback' => [
    'enabled' => true,
    'strategy' => 'previous',  // 'previous', 'latest', 'none'
    'add_header' => true,      // Add X-API-Version-Fallback header
],

Option	Description
enabled	Enable/disable fallback
strategy	previous = fallback to previous version, latest = fallback to latest, none = no fallback
add_header	Add X-API-Version-Fallback header when fallback is used

---

Sunset Behavior

How to handle requests to sunset (end-of-life) versions.

'sunset' => [
    'action' => 'reject',      // 'reject', 'warn', 'allow'
    'status_code' => 410,      // HTTP status code
    'include_migration_url' => true,
],

Action	Description
reject	Return error response (default)
warn	Allow request but add warning headers
allow	Allow request without warning

---

Response Headers

Automatically add version-related headers to responses.

'headers' => [
    'enabled' => true,
    'include' => [
        'version' => true,           // X-API-Version
        'status' => true,            // X-API-Version-Status
        'deprecation' => true,       // Deprecation (RFC 8594)
        'sunset' => true,            // Sunset (RFC 7231)
        'successor_link' => true,    // Link rel="successor-version"
    ],
],

See HTTP Headers for detailed information about each header.

---

Usage Tracking

Track API version usage for analytics and monitoring.

'tracking' => [
    'enabled' => env('API_VERSION_TRACKING', false),
    'driver' => 'database',      // 'database', 'redis', 'null'
    'table' => 'api_version_stats',
    'aggregate' => 'hourly',     // 'realtime', 'hourly', 'daily'
],

Option	Description
enabled	Enable/disable tracking
driver	Storage driver (database, redis, null)
table	Database table name (for database driver)
aggregate	Aggregation level

See Usage Tracking for detailed information.

---

Notifications

Get notified about version lifecycle events.

'notifications' => [
    'enabled' => false,
    'channels' => ['mail'],
    'recipients' => [],
    'events' => [
        'approaching_deprecation' => [7, 1],  // days before
        'approaching_sunset' => [30, 7, 1],
        'high_deprecated_usage' => 50,        // percentage threshold
    ],
],

---

Documentation

URLs for API documentation (used in error responses).

'documentation' => [
    'base_url' => env('API_DOCS_URL'),
    'migration_guides' => [
        // 'v1' => 'https://docs.example.com/api/migration/v1-to-v2',
    ],
],

---

Middleware

Middleware configuration for API version handling.

'middleware' => [
    'group' => 'api',            // Apply to this middleware group
    'alias' => 'api.version',    // Middleware alias
],

---

Environment Variables

Quick reference for environment variables:

Variable	Default	Description
API_VERSION_STRATEGY	uri	Detection strategy
API_DEFAULT_VERSION	latest	Default version
API_VERSION_TRACKING	false	Enable tracking
API_VENDOR	api	Vendor name for Accept header
API_DOCS_URL	null	Documentation base URL

---

Complete Example

<?php

return [
    'strategy' => 'uri',

    'strategies' => [
        'uri' => [
            'prefix' => 'api',
            'pattern' => 'v{version}',
        ],
        'header' => [
            'name' => 'X-API-Version',
        ],
        'query' => [
            'parameter' => 'api_version',
        ],
        'accept' => [
            'pattern' => 'application/vnd.{vendor}.{version}+json',
            'vendor' => 'myapp',
        ],
    ],

    'default_version' => 'latest',

    'fallback' => [
        'enabled' => true,
        'strategy' => 'previous',
        'add_header' => true,
    ],

    'sunset' => [
        'action' => 'reject',
        'status_code' => 410,
        'include_migration_url' => true,
    ],

    'headers' => [
        'enabled' => true,
        'include' => [
            'version' => true,
            'status' => true,
            'deprecation' => true,
            'sunset' => true,
            'successor_link' => true,
        ],
    ],

    'tracking' => [
        'enabled' => true,
        'driver' => 'database',
        'table' => 'api_version_stats',
        'aggregate' => 'hourly',
    ],

    'documentation' => [
        'base_url' => 'https://docs.myapp.com/api',
        'migration_guides' => [
            'v1' => 'https://docs.myapp.com/api/migration/v1-to-v2',
        ],
    ],

    'middleware' => [
        'group' => 'api',
        'alias' => 'api.version',
    ],
];

---

Next Steps

• Detection Strategies - Deep dive into versioning strategies
• HTTP Headers - RFC-compliant response headers
• Usage Tracking - Monitor API usage