Public API for Resource behavior metadata #14

New issue

Closed

opened 2026-05-27 08:32:40 +02:00 by c.fahner · 1 comment

c.fahner commented

2026-05-27 08:32:40 +02:00

Owner

Currently the actual behavior of a Resource is inaccessible from outside of the Handler black box. It is not possible to:

Get a list of HTTP methods for a resource
Get a list of parameters for a resource method
Get the extractors and validators of a specific resource method parameter

While it would be possible to use reflection on the Resource class to obtain this information, this would only show the information as declared and not how it actually behaves. For example, every resource has implied HEAD and OPTIONS methods and every parameter has an implied FromQuery extractor. Future versions may further introduce new implied, edge-case, documentation, or security-related behavior.

There should be a public API that standardizes this "behavioral metadata" about resources. Implementing OpenAPI would be impossible otherwise. The Handler itself should also be refactored to use these API's instead of its own internal methods, to keep the metadata in sync with the actual behavior.

Suggestion: a final class Resource\Endpoint and a namespace with the same name that contains all the helpers (Resource\Endpoint\{ Method, Parameter, StringParameter, ... }.

Currently the actual behavior of a `Resource` is inaccessible from outside of the `Handler` black box. It is not possible to: * Get a list of HTTP methods for a resource * Get a list of parameters for a resource method * Get the extractors and validators of a specific resource method parameter While it would be possible to use reflection on the `Resource` class to obtain this information, this would only show the information as declared and not how it actually behaves. For example, every resource has implied `HEAD` and `OPTIONS` methods and every parameter has an implied `FromQuery` extractor. Future versions may further introduce new implied, edge-case, documentation, or security-related behavior. There should be a public API that standardizes this "behavioral metadata" about resources. Implementing OpenAPI would be impossible otherwise. The `Handler` itself should also be refactored to use these API's instead of its own internal methods, to keep the metadata in sync with the actual behavior. Suggestion: a final class `Resource\Endpoint` and a namespace with the same name that contains all the helpers (`Resource\Endpoint\{ Method, Parameter, StringParameter, ... }`.

c.fahner added this to the v0.1 milestone

2026-05-27 08:32:40 +02:00

c.fahner added the

Status

Blocked

Kind/Feature

labels

2026-05-27 08:32:40 +02:00

c.fahner added a new dependency

2026-05-27 08:33:05 +02:00

#10 Declarable HTTP resources

c.fahner added a new dependency