Skip to main content

REST Expanders 2.3.0

· 4 min read
Frédéric Hannes
Frédéric Hannes
R&D Engineer

RestFacade removal​

The RestFacade class which was used previously in the control layer as a bridge between the Connector and Agent classes has been removed. This was an old artifact left from the original REST JAX-RS implementation for the NS application stack. This class was intended to provide some encapsulation, but it did not really encapsulate anything and violated data version transparency.

  • $dataElement.name$RestFacade.create$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.create$dataElement.name$() method.
  • $dataElement.name$RestFacade.modify$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.put$dataElement.name$() method.
  • $dataElement.name$RestFacade.update$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.patch$dataElement.name$() method.
  • $dataElement.name$RestFacade.remove$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.delete$dataElement.name$() method.
  • $dataElement.name$RestFacade.fetch$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.get$dataElement.name$Details() method, where the SearchDetails is now also constructed.
  • $dataElement.name$RestFacade.fetch$dataElement.name$List(): This method was integrated into the $dataElement.name$Connector.get$dataElement.name$DetailsList() method, where the SearchDetails is now also constructed with support for sort parameters.
  • $dataElement.name$RestFacade.applyPagination(): This method was moved to a new class $dataElement.name$Pagination.
  • $dataElement.name$RestFacade.DEFAULT_PAGE: This constant was moved to a new class $dataElement.name$Pagination.
  • $dataElement.name$RestFacade.DEFAULT_PAGE_SIZE: This constant was moved to a new class $dataElement.name$Pagination.
  • $dataElement.name$RestFacade.MAX_PAGE_SIZE: This constant was moved to a new class $dataElement.name$Pagination.
caution

The $dataElement.name$Pagination class may still be revisited in the future to improve its design.

All existing custom methods that were placed in the RestFacade class should be either integrated into their respective callers or be properly encapsulated if required in its own custom class. To provide some backwards compatibility for transitioning, the expansion of the RestFacade class can still be enabled with the transient option jaxrs.transient.generateFacade.enable. All expanded endpoints will no longer use the RestFacade even if this transient option is defined.

caution

The transient option jaxrs.transient.generateFacade.enable was removed in rest-expanders version 3.0.0.

Sorting​

Default Order​

For some time data returned by the GETlist endpoints was always sorted ascending by database identifier by default if no other sorting was enforced in the DataElement's QuerySearch class. This functionality was removed after the querysearch-expanders split off from the rest-expanders, as for many requests it does not make sense to deteriorate query performance by always enforcing a default order.

Not having this default ordering for the REST apis created an issue with results returned by the query not always being consistently ordered in between multiple calls. As a result, paginated results do not always make sense as resources can will sometimes shift places in the results.

The querysearch-expanders introduced the option useDefaultOrder on the QuerySearch metamodel element, which is implicitly created by the rest-expanders. This option is now always added to that QuerySearch instance as well, so the default ordering by database identifier is always enforced for the REST API. Contrary to the original implementation, the ordering by database identifier is also enforced if other ordering is applied to the query, but it is added as the last order in the chain.

If for some reason it is required to disable this default ordering, this can still be achieved per individual DataElement by setting the default order to false on the queryBuilder in the QuerySearch class:

// anchor:custom-query-before-build:start
queryBuilder.useDefaultOrder(false);
// anchor:custom-query-before-build:end

Sorting parameter​

This version of the REST expanders introduces sorting of results returned by the GETlist endpoint through a query parameter sortby. This parameter is now always added to the expanded endpoints. It can however be disabled by adding the option jaxrs.endpoint.getList.sorting.disable to the DataElement or for the entire Component by adding the option jaxrs.endpoint.getList.sorting.disable to the Component.

Miscellaneous​

  • All ValidationError constants in the ValidationError class are now marked final. They should always be fixed. Any deviations should be registered as new error codes.
  • The pagination anchors were removed from the applyPagination() method, as pagination parameters can now be set through expansion options.