An endpoint should return an instance of a RepresentationModel if the response is a representation of the resource. You can obtain an instance of a RepresentationModel by using the build method of a RepresentationModel.Builder instance. The RepresentationModel.Builder method begins a RepresentationModel.Builder instance. The following builder methods are available:
State Builder Method
The state(Object pState) bean or dynamic bean holds the current state of the resource, for example a repository item or an Order bean. This object is filtered and rendered by the framework into the media type, and can be null, although it would normally be null only for collection resources.
Properties Builder Methods
The property or properties method allows you to add metadata properties for the resource to the response. The format for these methods should be property(String pkey, String pValue) or properties(Map <String, String> pProperties).
Links Builder Method
The links method allows additional links to be specified for the resource. Generally, an endpoint will not need to do this, since all standard HATEOAS links are automatically added. However, you may occasionally want to add additional links to an endpoint, for example, to endpoints outside of the current resource.
Use the format links(Links… pLinks) when using this method.
Note: A link URI appearing in a response should use an absolute path or the full path. However, it is best when coding resources to use relative URIs and allow the framework to turn it into an absolute URI.
Self Builder Methods
Although not generally required by an endpoint, the self method allows you to specify a self link. You may want to identify a custom self link or an endpoint may build a representation for a resource that is not currently in context. Use the format self(Link pSelf) when using this method.
The self(String pSelfUri) method takes the URI of the self link.
Exclude Link Relation Builder Method
The excludeLinkRelation method allows an endpoint to specifically exclude an automatically generated link from the response. Use the format excludeLinkRelation(String… pLinkRelations) when using this method.
Embedded Builder Method
The embedded method allows you to add the URI of any resource that should be embedded in the response. For example, the commerce item resource may embed a product resource URI. The framework retrieves the embedded resource if it is not filtered out. Use the format embedded(String pRel, String… pURIs) when using this method.
An embedded URI can be created using the LinkUtils.instance().buildResourceUri method.
Members Builder Method
An endpoint that returns a collection resource representation should use the members method to set the members of the collection. Use the format members(String… pMemberURIs) when using this method. Member URIs can be created using the LinkUtils.instance().buildMemberUri method.
Resource Type Builder Method
The ResourceType method allows you to specify if the RepresentationModel is for a collection or a singular resource. Use the format resourceType (ResourceType pResourceType) when using this method.
Override Filter ID Builder Method
The overrideFilterId method allows you to set up an endpoint that specifies the filter ID to use when rendering this RepresentationModel. By default, the framework uses filter ID associated with the @Endpoint annotation of the endpoint method. Use the format overrideFilterId(String pOverrideFilterId) format when using this method.
Status Builder Methods
By default, a RepresentationModel response uses a 200 (OK) status code. However, you may want to respond with a different status code at times. For example, creating a new resource using a POST endpoint method would require responding with a 201 (CREATED) status and should include a LOCATION header with a URI to the new resource. An endpoint may also respond with a 202 (ACCEPTED) status code.
Use the format status(int pStatus), created(URI pLocation) or accepted when using these methods.
Header Builder Methods
A response can also include additional headers, which have specific methods that support the CONTENT_LANGUAGE and LOCATION headers. Use the format header(String pName, Object pHeader), language(Locale pLanguage) or location(URI pLocation) when using these methods.
Additional State Builder Method
You can add secondary state objects to the response with the additionalState method. Use the format additionalState (String pKey, Object pState) when using this method.
Language Builder Method
This method sets the language header for the specified locale. Use the format language (Locale pLanguage) when using this method.
Location Builder Method
This method allows you to add a location header for the given URI. Use the format location (Locale plocation) when using this method.
Listing Response Builder Method
You can allow pagination links and properties to be included when getting a response for a collection resource by setting the listingResponse method. Use the format listingResponse (ListingResponse pListingResponse) when using this method.
Version Builder Method
At times, it may be necessary to explicitly set the version of a resource. Use the version method for this. Use the format version (int pVersion) when using this method.
