Getting Started

Getting Started

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

---

Basic Setup

1. Define Your First Version

Open routes/api.php and define your API versions:

use Grazulex\ApiRoute\Facades\ApiRoute;
use Illuminate\Support\Facades\Route;

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

2. 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:

use Grazulex\ApiRoute\Facades\ApiRoute;

// Version 1 - Deprecated
ApiRoute::version('v1', function () {
    Route::apiResource('users', App\Http\Controllers\Api\V1\UserController::class);
})
->deprecated('2025-06-01')
->sunset('2025-12-01');

// Version 2 - Current stable
ApiRoute::version('v2', function () {
    Route::apiResource('users', App\Http\Controllers\Api\V2\UserController::class);
})->current();

// Version 3 - Beta
ApiRoute::version('v3', function () {
    Route::apiResource('users', App\Http\Controllers\Api\V3\UserController::class);
})->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