APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

REST Collections

Expose typed APPNETOS Collections as context-aware REST resources.

Define resources through PHP attributes, keep data operations inside Collections, and let the shared REST runtime handle routing, resolution, method dispatch and responses.

Architecture & lifecycle

REST resources are APPNETOS Collection classes exposed through a PHP class attribute. The shared REST registry discovers mapped runtime collections, reads their REST annotations (including inherited annotations), and creates normalized resources indexed by slug. Their associated Document class is obtained from the Collection Database annotation.

The runtime coordinates the Router, Registry, Resolver, Controller, Result, Response and Log components. This keeps application-specific data operations in Collections while the shared REST infrastructure handles HTTP dispatch.

APPNETOS REST request flows through router, registry, resolver and controller to a mapped Collection, then returns a response.
A REST Collection is resolved from its annotation and the active application context, not from an arbitrary controller route.

Defining a REST Collection

Extend the APPNETOS Collection base, map its Document through the Collection Database annotation, and declare the public REST resource through Core\Rest\Annotation\Rest. The example below illustrates the annotation relationship; the Collection must also implement the REST operation methods it exposes.

use Core\Collection\Annotation\Database;
use Core\Collection\Base as CollectionBase;
use Core\Rest\Annotation\Rest;

#[Database(document: ExampleDocument::class)]
#[Rest(
    slug: 'items',
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
    active: true,
)]
class ExampleCollection extends CollectionBase
{
    // Implement the REST methods required by the enabled HTTP methods.
}

Important: The REST annotation has no document parameter. Document mapping belongs to Core\Collection\Annotation\Database.

REST annotation reference

Parameter Default Description
slug: string|null null Public resource slug; an empty or missing slug is rejected during registration.
methods: array ['GET'] Allowed HTTP methods for the resource.
active: bool true Inactive resources are excluded from the runtime registry.

Resource slugs must be unique within the active REST registry. Duplicate slugs cause a registration error. The registry also evaluates optional RateLimit, Log and Security annotations.

Routing and resource resolution

The Router normalizes the request URI, removes the active context prefix, and resolves the first remaining segment as the REST resource slug. A second segment, when present, becomes the resource identifier. The application host and configured context slug determine the externally visible URL.

GET /rest/items       # List resource items (illustrative context slug)
GET /rest/items/123   # Resolve item identifier 123

The Registry returns the resource metadata for the slug. The Resolver prepares the executable runtime and checks resource constraints before the Controller invokes Collection methods. A cached REST registry can avoid repeated reflection during initialization.

HTTP method dispatch

Method Collection operation Behavior
GET /resource restFind($filter, $options) List results with pagination metadata.
GET /resource/{id} restFindOneById($id) Retrieve one document.
POST /resource restValidateCreate($data) (optional), restCreate($data) Create and return status 201.
PUT /resource/{id} restReplace($id, $data) Replace an existing resource.
PATCH /resource/{id} restValidateUpdate($data) (optional), restUpdate($id, $data) Partially update a resource.
DELETE /resource/{id} restDelete($id) Delete and return a boolean result.

PUT, PATCH and DELETE require an identifier. The Controller verifies required Collection methods before calling them. A configured HTTP method does not automatically implement the corresponding Collection operation.

Validation, filtering and access

The Controller optionally calls restValidateCreate() before creation and restValidateUpdate() before partial updates. List requests process filters, sorting, limit and page options; an additional result is fetched to determine hasMore without a separate count query. Filter keys beginning with a MongoDB operator prefix are removed recursively.

Authentication is performed by the bootstrap security layer; the REST Resolver evaluates the resolved identity against resource security metadata and enforces relevant runtime constraints. Detailed payload validation, response formats and errors are covered in Request & Response; resource security and CORS are covered in Security & CORS.

Public API Reference

Core\Rest

Class & Registry

Class: Core\Rest

Extends: Core\Rest\Base

use Core\Rest;
use Core\Registry;

$rest = Registry::get(Rest::class);
Method Description
public function __construct() Construct the component.
public function init(): void Initialize runtime state or registry.
public function getRouter(): Router Return router.
public function getRegistry(): Registry Return registry.
public function getRequest(): Request Return REST request component.
public function getResolver(): Resolver Return resolver.
public function getController(): Controller Return controller.
public function getResponse(): Response Return response component.
Core\Rest\Annotation

Class & Registry

Class: Core\Rest\Annotation

Extends: Core\Rest\Annotation\Base

use Core\Rest\Annotation;
use Core\Registry;

$annotation = Registry::get(Annotations::class);
Method Description
public function __construct(string|null $slug = null, array $methods = ['GET'], bool $active = true,) Construct the component.
public function getSlug(): string|null Read resource slug.
public function getMethods(): array Read allowed methods.
public function getActive(): bool Read activation flag.
public function isActive(): bool Check activation flag.
Core\Rest\Registry

Class & Registry

Class: Core\Rest\Registry

Extends: Core\Rest\Registry\Base

use Core\Rest\Registry as RestRegistry;
use Core\Registry;

$registry = Registry::get(RestRegistry::class);
Method signature Description
public function __construct() Construct the component.
public function init(): void Initialize runtime state or registry.
public function get(string|null $slug): Resource Resolve a registered resource by slug.
public function has(string|null $slug): bool Check whether a resource slug exists.
public function getResources(): array Return registered resources.
Core\Rest\Router

Class & Registry

Class: Core\Rest\Router

Extends: Core\Rest\Router\Base

use Core\RestRouter;
use Core\Registry;

$router = Registry::get(Router::class);
Method Description
public function __construct() Construct the component.
public function resolve(): Route Resolve an incoming route.
public function getRequestUri(): string Read the normalized request URI.
public function getSlug(): string Read resource slug.
public function getSegments(): array Read route segments.
public function getRuntimeSegments(): array Read runtime segments.
public function getResolved(): bool Read resolved state.
public function isResolved(): bool Check resolved state.
Core\Rest\Controller

Class & Registry

Class: Core\Rest\Controller

Extends: Core\Rest\Controller\Base

use Core\Rest\Controller;
use Core\Registry;

$controller = Registry::get(Controller::class);
Method signature Description
public function __construct() Construct the component.
public function init(): void Initialize runtime state or registry.
public function execute(Runtime $runtime): mixed Dispatch the resolved REST operation.
public function getRequest(): Request Return REST request component.

Next Steps

Previous

REST & OpenAPI

Explore REST & OpenAPI

Next

Request & Response

Explore Request & Response