Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

The active-version page shows the steady-state contract for the current collection endpoint: stable payload, stable header, no retirement noise.

How it works

Instead of rendering raw JSON directly, the feature page builds the live collection response server-side and presents the body with the key headers and operational notes around it.

Why it matters

A healthy API version should be easy to reason about. Consumers should see what stays stable and which metadata they can safely integrate against.

Key concepts

Active lifecycle: The version is current, supported, and free from deprecation or sunset warnings.
X-Api-Version: Response header that tells clients exactly which contract version answered the request.

Route GET /demo/api/active-version

Response 200 application/json

CLI curl -i -H "Accept: application/json" "http://localhost:9502/demo/api/active-version"

Header	Value
`Content-Type`	`application/json`
`X-Api-Version`	`2.0.0`

Active version payload

{
    "data": [
        {
            "slug": "air-purifier",
            "name": "Air Purifier",
            "price": 149.99,
            "description": "HEPA filter, 3 fan speeds, night mode.",
            "status": "active",
            "category": {
                "slug": "home",
                "name": "Home"
            },
            "rating": 3.3,
            "links": {
                "self": "/demo/api/v1/products/air-purifier",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "domain-driven-design",
            "name": "Domain-Driven Design",
            "price": 54.99,
            "description": "Eric Evans' seminal work on tackling complexity in software.",
            "status": "active",
            "category": {
                "slug": "books",
                "name": "Books"
            },
            "rating": 2.8,
            "links": {
                "self": "/demo/api/v1/products/domain-driven-design",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "ergonomic-chair",
            "name": "Ergonomic Chair",
            "price": 299.99,
            "description": "Mesh back, adjustable lumbar, 4D armrests.",
            "status": "active",
            "category": {
                "slug": "home",
                "name": "Home"
            },
            "rating": 2.8,
            "links": {
                "self": "/demo/api/v1/products/ergonomic-chair",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "foam-roller",
            "name": "Foam Roller",
            "price": 29.99,
            "description": "High-density EVA foam, 45 cm, textured surface.",
            "status": "active",
            "category": {
                "slug": "sports",
                "name": "Sports"
            },
            "rating": 3.5,
            "links": {
                "self": "/demo/api/v1/products/foam-roller",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "head-first-design-patterns",
            "name": "Head First Design Patterns",
            "price": 49.99,
            "description": "A brain-friendly guide to design patterns.",
            "status": "active",
            "category": {
                "slug": "books",
                "name": "Books"
            },
            "rating": 3.3,
            "links": {
                "self": "/demo/api/v1/products/head-first-design-patterns",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "linen-shirt",
            "name": "Linen Shirt",
            "price": 54.99,
            "description": "Breathable linen, relaxed fit, button-down collar.",
            "status": "active",
            "category": {
                "slug": "clothing",
                "name": "Clothing"
            },
            "rating": 2.5,
            "links": {
                "self": "/demo/api/v1/products/linen-shirt",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "portable-monitor",
            "name": "Portable Monitor",
            "price": 249.99,
            "description": "15.6\" IPS display, USB-C powered, 1080p.",
            "status": "active",
            "category": {
                "slug": "electronics",
                "name": "Electronics"
            },
            "rating": 3,
            "links": {
                "self": "/demo/api/v1/products/portable-monitor",
                "collection": "/demo/api/v1/products"
            }
        },
        {
            "slug": "power-bank",
            "name": "Power Bank",
            "price": 59.99,
            "description": "20000mAh, dual USB-C, fast charging.",
            "status": "active",
            "category": {
                "slug": "electronics",
                "name": "Electronics"
            },
            "rating": 3,
            "links": {
                "self": "/demo/api/v1/products/power-bank",
                "collection": "/demo/api/v1/products"
            }
        }
    ],
    "meta": {
        "representation": "json",
        "profile": "standard",
        "fields": [],
        "expand": [],
        "page": 1,
        "limit": 8,
        "total": 12,
        "query": null,
        "filters": []
    },
    "links": {
        "self": "/demo/api/v1/products"
    }
}

#[ApiVersion]

Verified against Semitexa Ultimate 2026.09.19.1020

Active Version

The active version should feel intentionally boring: same response shape, stable metadata, and no sunset chatter for clients to parse around.

How it works

#[ApiVersion] on the Payload DTO declares the version string and lifecycle state. When the state is active, the framework emits X-Api-Version on every response without additional lifecycle headers. No Deprecation header, no Sunset header — just a stable version token that makes the serving contract traceable in logs and observability tooling.

Why this matters

Clients get stable version traceability without deprecation churn. Migration pressure should disappear once a client is on the supported path. The JSON contract is identical in shape to older versions, but the lifecycle signal is clean — which is the expected steady state for any API route that is not under retirement pressure.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Api;67use App\Application\Payload\Api\ProductListV2Payload;8use App\Application\Resource\Api\ProductListV2Resource;9use App\Domain\Api\ProductApiReaderInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: ProductListV2Payload::class, resource: ProductListV2Resource::class)]15final class ProductListV2Handler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected ProductApiReaderInterface $reader;1920    public function handle(ProductListV2Payload $payload, ProductListV2Resource $resource): ProductListV2Resource21    {22        return $resource->fromProducts($this->reader->listCurrentVersion());23    }24}25

<?php

declare(strict_types=1);

namespace App\Application\Handler\Api;

use App\Application\Payload\Api\ProductListV2Payload;
use App\Application\Resource\Api\ProductListV2Resource;
use App\Domain\Api\ProductApiReaderInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ProductListV2Payload::class, resource: ProductListV2Resource::class)]
final class ProductListV2Handler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected ProductApiReaderInterface $reader;

    public function handle(ProductListV2Payload $payload, ProductListV2Resource $resource): ProductListV2Resource
    {
        return $resource->fromProducts($this->reader->listCurrentVersion());
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Payload\Api;67use App\Application\Resource\Api\ProductListV2Resource;8use Semitexa\Api\Attribute\ApiVersion;9use Semitexa\Api\Attribute\ExternalApi;10use Semitexa\Core\Attribute\AsPublicPayload;1112#[ExternalApi]13#[ApiVersion('2.0')]14#[AsPublicPayload(15    path: '/api/v2/products',16    methods: ['GET'],17    responseWith: ProductListV2Resource::class,18    produces: ['application/json'],19)]20final class ProductListV2Payload21{22}23

<?php

declare(strict_types=1);

namespace App\Application\Payload\Api;

use App\Application\Resource\Api\ProductListV2Resource;
use Semitexa\Api\Attribute\ApiVersion;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[ExternalApi]
#[ApiVersion('2.0')]
#[AsPublicPayload(
    path: '/api/v2/products',
    methods: ['GET'],
    responseWith: ProductListV2Resource::class,
    produces: ['application/json'],
)]
final class ProductListV2Payload
{
}

1<?php23declare(strict_types=1);45namespace App\Application\Api;67final class DemoApiPresenter8{9    public function productList(array $products): array10    {11        return [12            'data' => array_map(13                static fn (array $product): array => [14                    'id' => $product['id'],15                    'name' => $product['name'],16                    'price' => $product['price'],17                ],18                $products,19            ),20        ];21    }22}23

<?php

declare(strict_types=1);

namespace App\Application\Api;

final class DemoApiPresenter
{
    public function productList(array $products): array
    {
        return [
            'data' => array_map(
                static fn (array $product): array => [
                    'id' => $product['id'],
                    'name' => $product['name'],
                    'price' => $product['price'],
                ],
                $products,
            ),
        ];
    }
}

Version Notes

What this endpoint is proving

Concern	Behavior	Why it matters
Current version	The route emits `X-Api-Version: 2.0.0` and nothing else.	Clients get stable version traceability without deprecation churn.
Consumer expectation	The JSON contract is the same style as older versions, but with no retirement metadata.	Migration pressure should disappear once a client is on the supported path.

How it works

Instead of rendering raw JSON directly, the feature page builds the live collection response server-side and presents the body with the key headers and operational notes around it.

Why it matters

A healthy API version should be easy to reason about. Consumers should see what stays stable and which metadata they can safely integrate against.

Key concepts

Active lifecycle: The version is current, supported, and free from deprecation or sunset warnings.
X-Api-Version: Response header that tells clients exactly which contract version answered the request.

Find a concept, task, or command

Active Version

What this does

How it works

Why it matters

Key concepts

Current collection endpoint without lifecycle warnings

Active Version

How it works

Why this matters

What this endpoint is proving

How it works

Why it matters

Key concepts