API Versioning Implementation Plan

Document Version: 1.0 Created: 2026-01-21 Status: Draft Owner: Engineering Team

---

Executive Summary

This document outlines the implementation plan to resolve 30 critical and high-risk unversioned API endpoints identified in the API Versioning Audit. The primary goal is to migrate agentic workflow endpoints and dry-run session APIs to the v1 namespace, establishing a stable API contract for consumers.

Scope

Category	Endpoints	Risk Level	Priority
Agent Audit & Migration API	23	🔴 Critical	P0
Dry Run Sessions API	7	🔴 Critical	P0
Affiliates (Legacy-Only)	1	⚠️ High	P1
Webhooks	5	⚠️ High	P2

---

Phase 1: Critical API Migration (P0)

1.1 Add Versioned Routes for Agent Audit API

Objective: Migrate 23 Agent Audit endpoints from /api/agents/audit/* to /api/v1/agents/audit/*

File: routes/api_v1.php

Implementation:

Add the following route group to routes/api_v1.php after existing route definitions:

/*
|--------------------------------------------------------------------------
| Agent Audit & Migration API (v1)
|--------------------------------------------------------------------------
|
| Routes for agent configuration auditing, capability testing, and migration.
| Previously unversioned at /api/agents/audit, now stabilized under v1.
|
*/

use App\Extensions\ContentManager\System\Http\Controllers\AgentAuditController;

Route::prefix('agents/audit')->middleware(['auth:sanctum'])->group(function () {
    // Dashboard & Overview
    Route::get('/', [AgentAuditController::class, 'index']);
    Route::get('/company-analytics', [AgentAuditController::class, 'companyAnalytics']);
    Route::get('/marketplace-metrics', [AgentAuditController::class, 'marketplaceMetrics']);

    // Configuration
    Route::post('/recommend-configuration', [AgentAuditController::class, 'recommendConfiguration']);
    Route::post('/batch-migrate', [AgentAuditController::class, 'batchMigrate']);

    // Capability Testing
    Route::prefix('capabilities')->group(function () {
        Route::get('/', [AgentAuditController::class, 'listCapabilities']);
        Route::post('/estimate-cost', [AgentAuditController::class, 'estimateCapabilityCost']);
        Route::post('/model-recommendation', [AgentAuditController::class, 'getModelRecommendation']);
        Route::post('/{capability}/test', [AgentAuditController::class, 'testCapability']);
    });

    // Per-Agent Operations
    Route::prefix('{agent}')->group(function () {
        Route::get('/metrics', [AgentAuditController::class, 'agentMetrics']);
        Route::get('/validate', [AgentAuditController::class, 'validateConfiguration']);
        Route::post('/migrate', [AgentAuditController::class, 'migrate']);
        Route::post('/rollback', [AgentAuditController::class, 'rollbackMigration']);
        Route::post('/dry-run', [AgentAuditController::class, 'executeDryRun']);
        Route::post('/challenge', [AgentAuditController::class, 'challengeWorkflow']);
        Route::get('/marketplace-readiness', [AgentAuditController::class, 'testMarketplaceReadiness']);
        Route::post('/preview-capability', [AgentAuditController::class, 'previewCapability']);
        Route::post('/capability-models', [AgentAuditController::class, 'setAgentCapabilityModels']);
        Route::post('/dry-run-session', [AgentAuditController::class, 'createDryRunSession']);
    });
});

Verification:

php artisan route:list --path=api/v1/agents

---

1.2 Add Versioned Routes for Dry Run Sessions API

Objective: Migrate 7 Dry Run Session endpoints from /api/dry-run/sessions/* to /api/v1/dry-run/sessions/*

File: routes/api_v1.php

Implementation:

Add the following route group to routes/api_v1.php:

/*
|--------------------------------------------------------------------------
| Dry Run Sessions API (v1)
|--------------------------------------------------------------------------
|
| Routes for stateful dry-run conversation sessions with agents.
| Supports persona switching, memory management, and multi-turn conversations.
|
*/

use App\Http\Controllers\DryRun\DryRunSessionController;

Route::prefix('dry-run/sessions')->middleware(['auth:sanctum'])->group(function () {
    Route::get('/', [DryRunSessionController::class, 'index']);
    Route::post('/start', [DryRunSessionController::class, 'start']);

    Route::prefix('{token}')->group(function () {
        Route::get('/', [DryRunSessionController::class, 'show']);
        Route::post('/message', [DryRunSessionController::class, 'sendMessage']);
        Route::put('/persona', [DryRunSessionController::class, 'switchPersona']);
        Route::post('/reset', [DryRunSessionController::class, 'reset']);
        Route::post('/end', [DryRunSessionController::class, 'end']);
    });
});

Verification:

php artisan route:list --path=api/v1/dry-run

---

1.3 Add Deprecation Headers to Legacy Routes

Objective: Alert consumers using unversioned endpoints that they should migrate to v1.

File: app/Http/Middleware/DeprecatedApiWarning.php (new file)

Implementation:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class DeprecatedApiWarning
{
    /**
     * Deprecated route patterns that have v1 equivalents.
     */
    private array $deprecatedPatterns = [
        '/api/agents/audit' => '/api/v1/agents/audit',
        '/api/dry-run/sessions' => '/api/v1/dry-run/sessions',
        '/api/affiliates' => '/api/v1/affiliates',
    ];

    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);

        $path = $request->path();

        foreach ($this->deprecatedPatterns as $deprecated => $replacement) {
            if (str_starts_with('/' . $path, $deprecated)) {
                $response->headers->set('Deprecation', 'true');
                $response->headers->set('Sunset', '2026-07-01');
                $response->headers->set('Link', "<{$replacement}>; rel=\"successor-version\"");
                $response->headers->set(
                    'X-Deprecation-Notice',
                    "This endpoint is deprecated. Please migrate to {$replacement}. Sunset date: 2026-07-01."
                );
                break;
            }
        }

        return $response;
    }
}

Register in app/Http/Kernel.php:

protected $middlewareGroups = [
    'api' => [
        // ... existing middleware
        \App\Http\Middleware\DeprecatedApiWarning::class,
    ],
];

---

Phase 2: High-Priority Fixes (P1)

2.1 Add Missing Affiliates Endpoint to v1

Objective: The /api/affiliates/update-reference endpoint exists only in legacy. Add to v1 before sunset.

File: routes/api_v1.php

Implementation:

/*
|--------------------------------------------------------------------------
| Affiliates API (v1)
|--------------------------------------------------------------------------
*/

use App\Http\Controllers\Api\AffiliateApiController;

Route::prefix('affiliates')->middleware(['auth:sanctum'])->group(function () {
    Route::post('/update-reference', [AffiliateApiController::class, 'updateReference']);
});

---

Phase 3: Webhook Versioning (P2)

3.1 Webhook Versioning Strategy

Challenge: Webhook URLs are configured in third-party systems (Stripe, payment gateways) and are difficult to change.

Recommended Approach: Parallel routing with gradual migration.

Option A: Version in Path (Recommended)

// New versioned webhooks (preferred for new integrations)
Route::prefix('webhooks/v1')->group(function () {
    Route::match(['get', 'post'], '/{gateway}', [PaymentProcessController::class, 'handleWebhook']);
});

// Legacy webhooks (maintain indefinitely for existing integrations)
Route::match(['get', 'post'], '/webhooks/{gateway}', [PaymentProcessController::class, 'handleWebhook']);

Option B: Version in Header (Alternative)

Accept a X-Webhook-Version header and route internally:

// In PaymentProcessController@handleWebhook
$version = $request->header('X-Webhook-Version', 'legacy');

Decision Required: Discuss with stakeholders which third-party integrations are active before implementing.

---

Phase 4: Documentation & Communication

4.1 Update API Documentation

Tasks:

1. Update OpenAPI/Swagger spec to include v1 paths for:
2. /api/v1/agents/audit/* (23 endpoints)
3. /api/v1/dry-run/sessions/* (7 endpoints)

4. /api/v1/affiliates/* (1 endpoint)

5. Add deprecation notices to existing unversioned endpoint docs

6. Update Postman collection (see API_VERSIONING_AUDIT.md Part 5)

4.2 Consumer Communication

Draft Migration Notice:

## API Migration Notice - Action Required

**Effective Date:** 2026-02-01
**Sunset Date:** 2026-07-01

The following API endpoints are being migrated to versioned paths:

| Current (Deprecated) | New (v1) |
|---------------------|----------|
| `/api/agents/audit/*` | `/api/v1/agents/audit/*` |
| `/api/dry-run/sessions/*` | `/api/v1/dry-run/sessions/*` |
| `/api/affiliates/*` | `/api/v1/affiliates/*` |

**What you need to do:**
1. Update your API base URL to include `/v1`
2. Test your integration against the new endpoints
3. Complete migration before sunset date

**Deprecation headers:**
- `Deprecation: true`
- `Sunset: 2026-07-01`
- `Link: </api/v1/...>; rel="successor-version"`

---

Implementation Checklist

Pre-Implementation

• Review and approve implementation plan
• Identify active API consumers for agentic endpoints
• Set up monitoring for deprecated endpoint usage
• Prepare rollback plan

Phase 1: Critical Migration

• Add Agent Audit routes to api_v1.php
• Add Dry Run Session routes to api_v1.php
• Create DeprecatedApiWarning middleware
• Register middleware in Kernel
• Run route verification commands
• Test all 30 migrated endpoints

Phase 2: High-Priority Fixes

• Add Affiliates endpoint to v1
• Verify existing affiliate integrations

Phase 3: Webhooks

• Survey third-party webhook configurations
• Implement versioned webhook routes
• Coordinate with payment team

Phase 4: Documentation

• Update OpenAPI spec
• Update Postman collection
• Send migration notice to consumers
• Update internal documentation

Post-Implementation

• Monitor deprecated endpoint usage metrics
• Track consumer migration progress
• Review and adjust sunset date if needed
• Plan legacy route removal

---

Timeline

Phase	Description	Target
Phase 1	Critical API Migration	Week 1-2
Phase 2	Affiliates Endpoint	Week 2
Phase 3	Webhook Strategy	Week 3-4
Phase 4	Documentation	Week 2-4
Sunset	Remove deprecated routes	6 months post-launch

---

Risk Mitigation

Breaking Change Prevention

1. Parallel Routes: Both versioned and unversioned routes work during transition
2. Deprecation Headers: Clear warnings to consumers
3. Extended Sunset: 6-month migration window
4. Monitoring: Track usage of deprecated endpoints

Rollback Plan

If issues are discovered post-deployment:

1. Remove new v1 routes from api_v1.php
2. Remove DeprecatedApiWarning middleware
3. Deploy hotfix
4. Analyze issues before retry

---

Appendix A: File Changes Summary

File	Action	Lines Changed
routes/api_v1.php	Add routes	+60
app/Http/Middleware/DeprecatedApiWarning.php	Create	+45
app/Http/Kernel.php	Register middleware	+1
docs/API_VERSIONING_AUDIT.md	Update status	Minor

Appendix B: Endpoint Migration Reference

Agent Audit API (23 endpoints)

#	Method	Legacy Path	v1 Path
1	GET	/api/agents/audit/	/api/v1/agents/audit/
2	GET	/api/agents/audit/company-analytics	/api/v1/agents/audit/company-analytics
3	GET	/api/agents/audit/marketplace-metrics	/api/v1/agents/audit/marketplace-metrics
4	POST	/api/agents/audit/recommend-configuration	/api/v1/agents/audit/recommend-configuration
5	POST	/api/agents/audit/batch-migrate	/api/v1/agents/audit/batch-migrate
6	GET	/api/agents/audit/capabilities/	/api/v1/agents/audit/capabilities/
7	POST	/api/agents/audit/capabilities/estimate-cost	/api/v1/agents/audit/capabilities/estimate-cost
8	POST	/api/agents/audit/capabilities/model-recommendation	/api/v1/agents/audit/capabilities/model-recommendation
9	POST	/api/agents/audit/capabilities/{capability}/test	/api/v1/agents/audit/capabilities/{capability}/test
10	GET	/api/agents/audit/{agent}/metrics	/api/v1/agents/audit/{agent}/metrics
11	GET	/api/agents/audit/{agent}/validate	/api/v1/agents/audit/{agent}/validate
12	POST	/api/agents/audit/{agent}/migrate	/api/v1/agents/audit/{agent}/migrate
13	POST	/api/agents/audit/{agent}/rollback	/api/v1/agents/audit/{agent}/rollback
14	POST	/api/agents/audit/{agent}/dry-run	/api/v1/agents/audit/{agent}/dry-run
15	POST	/api/agents/audit/{agent}/challenge	/api/v1/agents/audit/{agent}/challenge
16	GET	/api/agents/audit/{agent}/marketplace-readiness	/api/v1/agents/audit/{agent}/marketplace-readiness
17	POST	/api/agents/audit/{agent}/preview-capability	/api/v1/agents/audit/{agent}/preview-capability
18	POST	/api/agents/audit/{agent}/capability-models	/api/v1/agents/audit/{agent}/capability-models
19	POST	/api/agents/audit/{agent}/dry-run-session	/api/v1/agents/audit/{agent}/dry-run-session

Dry Run Sessions API (7 endpoints)

#	Method	Legacy Path	v1 Path
1	GET	/api/dry-run/sessions/	/api/v1/dry-run/sessions/
2	POST	/api/dry-run/sessions/start	/api/v1/dry-run/sessions/start
3	GET	/api/dry-run/sessions/{token}	/api/v1/dry-run/sessions/{token}
4	POST	/api/dry-run/sessions/{token}/message	/api/v1/dry-run/sessions/{token}/message
5	PUT	/api/dry-run/sessions/{token}/persona	/api/v1/dry-run/sessions/{token}/persona
6	POST	/api/dry-run/sessions/{token}/reset	/api/v1/dry-run/sessions/{token}/reset
7	POST	/api/dry-run/sessions/{token}/end	/api/v1/dry-run/sessions/{token}/end

Affiliates API (1 endpoint)

#	Method	Legacy Path	v1 Path
1	POST	/api/affiliates/update-reference	/api/v1/affiliates/update-reference

---

Document Version: 1.0 Last Updated: 2026-01-21