info.magnolia.rest

Annotation Type DynamicPath

@Target(value=TYPE)
 @Retention(value=RUNTIME)
public @interface DynamicPath

Identifies REST endpoints for which Magnolia computes the endpoint base-path from config, dynamically at runtime.

This allows multiple EndpointDefinitions to be registered with identical implementationClass, yet potentially different parameters, at distinct base-paths.

The dynamic path is primarily deduced from the convention further below, and is relative to the ApplicationPath. The regular Path annotations (both class-level and method-level) are in turn relativized against the dynamic path. They may thus be set to root-path ("/").

File path (under /restEndpoints)	Endpoint path
/stories.yaml	/.rest/stories
/delivery/stories.yaml	/.rest/delivery/stories
/stories/v3.yaml (1)	/.rest/stories/v3
/stories_v3.yaml (2)	/.rest/stories/v3
/delivery/stories_v3.yaml	/.rest/delivery/stories/v3

1. example 3rd revision of an endpoint definition
2. alternative supported syntax to keep a meaningful file name

Versioning strategies differ between dynamic and regular endpoints. In regular endpoints, the version is part of the Path annotation and is up to the implementor. In dynamic endpoints, the version mark is supported in the YAML config path. This allows for EndpointDefinition evolution, without updating the implementation; this also helps existing consumers to maintain their contract with "previous" APIs. Using a versioned config/endpoint is not mandatory, but is a recommendation.