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

Semitexa REST is explicit and typed. Payload DTOs own the route contract, version markers stay visible, and the response shape remains reviewable instead of drifting into improvised controller code.

How it works

A REST endpoint is declared on a payload with #[AsPayload], then marked as machine-facing with #[ExternalApi]. Optional concerns such as versioning, sparse fieldsets, expand parameters, and alternative representations stay attached to that same contract instead of being scattered through middleware and controllers.

Why it matters

REST should not mean accidental complexity. Semitexa keeps the HTTP surface boring in the best way: one clear route contract, one clear execution path, and machine-facing behavior that is explicit in code review.

Key concepts

#[AsPayload]: The typed request contract that owns the REST route.
#[ExternalApi]: Marks the payload as a public machine-facing REST endpoint.
#[ApiVersion]: Attaches explicit lifecycle metadata to a REST contract.

Collection /demo/api/v1/products?q=headphones

Detail /demo/api/v1/products/wireless-headphones?profile=full&expand=category,reviews

JSON-LD /demo/api/v1/products/wireless-headphones?format=ld

Consumer	Headers / Params	Outcome
Frontend	`Accept: application/json \| X-Response-Profile: minimal`	Slim payload for interactive UI rendering.
Crawler	`Accept: application/ld+json`	Schema.org product document with semantic fields.
Dashboard	`Accept: application/json \| expand=category,reviews \| X-Response-Profile: full`	Expanded graph for internal admin views.
Search	`Accept: application/json \| q=headphones`	Filtered collection with pagination metadata.

application/ld+json fields expand

Verified against Semitexa Ultimate 2026.09.19.1020

REST API

Semitexa REST endpoints use typed Payload DTOs as the contract boundary — no controller sprawl, no magic annotation wiring, and no separate serializer configuration step.

How it works

Mark a Payload with #[ExternalApi] to opt it into the machine-facing API surface. Add #[ApiVersion] to set version metadata and emit X-Api-Version on every response. The same handler can respond to JSON, JSON-LD, and sparse field requests by reading negotiation signals from the request without branching the route.

Why this matters

One endpoint can serve multiple API consumers without branching into separate handler trees. The contract is visible in the Payload DTO, the version is declared on the attribute, and the response shape is shaped from a typed presenter — not from ad-hoc json_encode calls scattered across the handler.

1<?php23declare(strict_types=1);45namespace App\Api\Product;67use Semitexa\Api\Attribute\ApiVersion;8use Semitexa\Api\Attribute\ExternalApi;9use Semitexa\Core\Attribute\AsPublicPayload;1011#[AsPublicPayload(path: '/api/v1/products', methods: ['GET'], responseWith: ProductApiResponse::class)]12#[ExternalApi(version: 'v1')]13#[ApiVersion(version: '1.0.0')]14final class ProductListPayload15{16    protected int $page = 1;17    protected int $limit = 24;1819    public function getPage(): int { return $this->page; }20    public function setPage(int|string|null $page): void { $this->page = max(1, (int) ($page ?? 1)); }2122    public function getLimit(): int { return $this->limit; }23    public function setLimit(int|string|null $limit): void { $this->limit = min(100, max(1, (int) ($limit ?? 24))); }24}25

<?php

declare(strict_types=1);

namespace App\Api\Product;

use Semitexa\Api\Attribute\ApiVersion;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[AsPublicPayload(path: '/api/v1/products', methods: ['GET'], responseWith: ProductApiResponse::class)]
#[ExternalApi(version: 'v1')]
#[ApiVersion(version: '1.0.0')]
final class ProductListPayload
{
    protected int $page = 1;
    protected int $limit = 24;

    public function getPage(): int { return $this->page; }
    public function setPage(int|string|null $page): void { $this->page = max(1, (int) ($page ?? 1)); }

    public function getLimit(): int { return $this->limit; }
    public function setLimit(int|string|null $limit): void { $this->limit = min(100, max(1, (int) ($limit ?? 24))); }
}

1<?php23declare(strict_types=1);45namespace App\Api\Product;67use App\Api\Product\ProductApiResponse;8use Semitexa\Api\Attribute\ApiVersion;9use Semitexa\Api\Attribute\ExternalApi;10use Semitexa\Core\Attribute\AsPublicPayload;1112#[AsPublicPayload(path: '/api/v1/products/{slug}', methods: ['GET'], responseWith: ProductApiResponse::class)]13#[ExternalApi(version: 'v1')]14#[ApiVersion(version: '1.0.0')]15final class ProductDetailPayload16{17    protected string $slug = '';1819    public function getSlug(): string { return $this->slug; }20    public function setSlug(string $slug): void { $this->slug = trim($slug); }21}22

<?php

declare(strict_types=1);

namespace App\Api\Product;

use App\Api\Product\ProductApiResponse;
use Semitexa\Api\Attribute\ApiVersion;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[AsPublicPayload(path: '/api/v1/products/{slug}', methods: ['GET'], responseWith: ProductApiResponse::class)]
#[ExternalApi(version: 'v1')]
#[ApiVersion(version: '1.0.0')]
final class ProductDetailPayload
{
    protected string $slug = '';

    public function getSlug(): string { return $this->slug; }
    public function setSlug(string $slug): void { $this->slug = trim($slug); }
}

1GET /api/v1/products?page=1&limit=24 HTTP/1.12Accept: application/json3

GET /api/v1/products?page=1&limit=24 HTTP/1.1
Accept: application/json

How it works

Why it matters

Key concepts

#[AsPayload]: The typed request contract that owns the REST route.
#[ExternalApi]: Marks the payload as a public machine-facing REST endpoint.
#[ApiVersion]: Attaches explicit lifecycle metadata to a REST contract.

Find a concept, task, or command

REST API

What this does

How it works

Why it matters

Key concepts

One dataset, multiple machine-facing shapes

REST API

How it works

Why this matters

How it works

Why it matters

Key concepts