Collection resources that return a representation of each member of a collection might create performance problems. Therefore, the framework provides a mechanism to call the singular resource directly, based on the URI, for every member of a collection. This allows you to retrieve a representation without needing to call the singular resource for each member of a collection. You can pass an array of the strings that represent the URI path to each individual member of the collection by using the members method. Or, you can pass an array of Jersey link objects that contain the self link to each individual member of the collection.

You can retrieve a static instance of the LinkUtils component by using the getLinksUtils() method. Use the buildMemeberUris method to generate member URIs for collection resources and the buildResourceUri method to generate a URI for any resource with a given resource ID.

The embedded tag of the payload schema determines if the embedded members are included in the output. Refer to the Validating Input and Filtering Output section for additional information on the payload schema used for collection resources.

Note: If a collection resource endpoint responds with a singular resource representation model, the endpoint must generate a self link for the model using the selfLinkFromContext (true, singular ID) method of LinkUtils.

Should you require a collection resource endpoint that uses query parameters, you can configure your custom endpoint to support the q query parameter. The value of the q query parameter should be an RQL query string that can be applied to the resource. For example:

/public/v1/skus?q=margin>1.0

The collection endpoint can use the ListingRequestUtils class to construct a listing request from query parameters. Use the executeItemQuery method to invoke the q query parameter and return a valid listing response for the collection. For example:

ListingResponse<RepositoryItem> response;
try {
  response = ListingRequestUtils.executeItemQuery(
          LinkUtils.instance().getCurrentQueryParameters(),
          getCatalogTools().getCatalog().getItemDescriptor("sku"),
          "id");

} catch (Exception e) {
  throw RestUtils.createException("Failed to query for skus", e);
}