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.
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. |