Getting Started

Getting Started

Get your first API version up and running in 5 minutes.

---

Basic Setup

1. Create Your Route File

Create a route file for your API version:

mkdir -p routes/api
touch routes/api/v1.php

Add your routes to routes/api/v1.php:

<?php

use Illuminate\Support\Facades\Route;

Route::get('users', function () {
    return response()->json(['message' => 'API v1']);
});

2. Configure the Version

Add the version to config/apiroute.php:

'versions' => [
    'v1' => [
        'routes' => base_path('routes/api/v1.php'),
        'status' => 'active',
    ],
],

3. Test Your API

Make a request to your versioned endpoint:

curl http://your-app.test/api/v1/users

Response:

{
    "message": "API v1"
}

With headers:

HTTP/1.1 200 OK
X-API-Version: v1
X-API-Version-Status: active

---

Multiple Versions

Define multiple API versions with different statuses in config/apiroute.php:

'versions' => [
    'v1' => [
        'routes' => base_path('routes/api/v1.php'),
        'status' => 'deprecated',
        'deprecated_at' => '2025-06-01',
        'sunset_at' => '2025-12-01',
    ],
    'v2' => [
        'routes' => base_path('routes/api/v2.php'),
        'status' => 'active',
    ],
    'v3' => [
        'routes' => base_path('routes/api/v3.php'),
        'status' => 'beta',
    ],
],

---

Using Controllers

Create Version-Specific Controllers

Organize your controllers by version:

app/Http/Controllers/Api/
├── V1/
│   └── UserController.php
├── V2/
│   └── UserController.php
└── V3/
    └── UserController.php

Scaffold a New Version

Use the Artisan command to create a new version:

# Create empty version
php artisan api:version v2

# Copy from existing version
php artisan api:version v2 --copy-from=v1

---

Using the Facade

Access version information anywhere in your application:

use Grazulex\ApiRoute\Facades\ApiRoute;

// Get the current request version
$version = ApiRoute::resolveVersion(request());

// Get all registered versions
$versions = ApiRoute::versions();

// Check if a version exists
if (ApiRoute::hasVersion('v2')) {
    // ...
}

// Check version status
if (ApiRoute::isDeprecated('v1')) {
    // ...
}

---

Using Helpers

Global helper functions are available:

// Get current API version
$version = api_version(); // Returns 'v1', 'v2', etc.

// Get version definition object
$definition = api_version_definition();

---

Using Request Macros

Request macros provide convenient access to version information:

class UserController extends Controller
{
    public function index(Request $request)
    {
        // Get version string
        $version = $request->apiVersion(); // 'v1'

        // Get version status enum
        $status = $request->apiVersionStatus(); // VersionStatus::Active

        // Check if deprecated
        if ($request->isDeprecatedVersion()) {
            // Log warning
        }

        // Get full definition
        $definition = $request->apiVersionDefinition();
    }
}

---

Check Status

View the status of all your API versions:

php artisan api:status

Output:

┌─────────┬────────────┬──────────────┬──────────────┬────────────┐
│ Version │ Status     │ Deprecated   │ Sunset       │ Usage (30d)│
├─────────┼────────────┼──────────────┼──────────────┼────────────┤
│ v3      │ beta       │ -            │ -            │ 2.1%       │
│ v2      │ active     │ -            │ -            │ 78.4%      │
│ v1      │ deprecated │ 2025-06-01   │ 2025-12-01   │ 19.5%      │
└─────────┴────────────┴──────────────┴──────────────┴────────────┘

---

Next Steps

• Configuration - Customize the package
• Detection Strategies - Choose how versions are detected
• Version Lifecycle - Manage deprecation and sunset
• Examples - More detailed examples