Sub-resources, unlike resources, do not have a class level @Path annotation. They are invoked using sub-resource locator methods from their parent resource. For example, the CartRestResource class uses a sub-resource locator method that retrieves the CommerceItemRestSubresource. Sub-resource locator methods must have a @Path annotation and should not have a @httpMethods annotation. Locator methods must also contain a @SubresourceLocator annotation that contains the IDs of the sub-resources that can be returned by the method. If the sub-resource is globally scoped, the locator method should return an instance of the sub-resource. If the sub-resource is request-scoped, the locator method should return the class of the sub-resource.
The RestUtils class contains a static utility method that you can use to return the sub-resource. To do this, use the getResourceReference (String pResourceId) method, which calls into the getSubresource (String pSubresourceId) method in the current REST resource registry.
Note: If your sub-resource is composed of multiple classes or components, do not use the RestUtils.getResourceReference method. You can obtain the current registry using the RestUtils static utility method getCurrentRegistry. Then the registry getSubresourceByEndpointId (String pEndpointId) method can be used where the endpoint ID is an endpoint in the specific class or component you want to return.
Adding Sub-Resources
When an endpoint response should include sub-resources, you can embed them in the RepresentationModel. For example, you could retrieve order resources along with commerce items as sub-resources. The framework allows you to include the embedded resource when it is provided in an endpoint method. Note that you can add both singular and collection resources.
You can add sub-resources by performing the following steps:
Identify the embedded resource ID that needs to be embedded into the response.
Identify the relation name that will be added to the response to hold the embedded resource. It is a good idea to use compact URIs (curies) that allows you to define a generic syntax for addressing your URI. For example,
oc:commerceItems.Use the
LinkUtils.instance.buildResourceUri(…)to create the URI.Add the URI when you build the
RepresentationModelof the resource. The following is an example of an order with a sub-resource.RepresentationModel model = new RepresentationModel.Builder()
.state(order)
// hold the commerce items in property name "oc:commerceItems"
.embedded("oc:commerceItems", commerceItemsUri)
.build();
Note: If a parent resource has access controls configured, its sub-resources will have the same configuration. If you use the RestResourceRegistry component in the Dynamo Server Admin to review security, it will display only the parent’s access, even though the sub-resource also uses the same access.
