semitexa / api

2026.09.11.0529 2026-09-10 19:14 UTC

Requires

• php: ^8.4
• semitexa/auth: *
• semitexa/core: *

Requires (Dev)

• semitexa/authorization: *

MIT

• Semitexa

• api
• versioning
• m2m
• semitexa
• machine-auth

Published on Packagist.org on 2026-09-11 05:39 UTC

README

External API product layer for Semitexa with machine-to-machine authentication, versioned routes, and structured error envelopes.

Purpose

Provides the opt-in external API surface for Semitexa applications. Routes marked with #[ExternalApi] receive machine-facing JSON error envelopes for domain failures, Bearer token M2M authentication via MachineAuthHandler, and API versioning with #[ApiVersion] including deprecation and sunset headers.

Role in Semitexa

Depends on semitexa/core and semitexa/auth. Enriches Core's route metadata with external_api and api_version extension keys via ApiRouteMetadataResolver. Internal routes remain completely unaffected by this package.

Key Features

• #[ExternalApi] attribute for opt-in API route designation
• #[ApiVersion] with deprecation and sunset metadata headers
• MachineAuthHandler supporting Bearer {id}:{secret} token format
• ExternalApiExceptionMapper producing machine-readable JSON error envelopes for DomainException routes and falling back to Core's generic 500 response for unexpected throwables
• MachinePrincipal implementing AuthenticatableInterface
• MachineCredential entity with scopes, revocation, and audit support

Notes

Only routes explicitly marked with #[ExternalApi] receive API behavior. All other routes continue to use Core's default exception mapping and response handling.