13 posts tagged with "rest-expanders"

REST Expanders are now capable of generating fully featured interactions with file resources. Several other fixes and improvements were also implemented. This post will cover many of the improvements introduced from version 4.22.0 to 4.26.0. The latter of which we consider to provide a complete and stable implementation of the file support.

Resources​

The expansion resource below provide rest-expanders 4.26.0.

Changes and improvements​

File support​

Version 4.26.0 of rest-expanders features the finished implementation for file support. This includes the linking of file resources to regular REST resources, endpoints to upload files and endpoints to download files.

Files are always represented as fields of a REST resource. It is possible to add the option svcapi.endpoint.upload to generate an upload endpoint in function of a field and svcapi.endpoint.download to generate a download endpoint.

An upload endpoint will return a header containing a unique identifier for the file that can passed to the resource endpoints to link it to a new or existing resource.

{
  "name": "Snickers",
  "uuid": "f9020d14-b1ab-4de3-99a2-f0a2e5a8c71d",
  "birthCertificate": {
    "resourceUri": "http://localhost:8080/restexample/v1/cats/f9020d14-b1ab-4de3-99a2-f0a2e5a8c71d/download/birthCertificate",
    "identifier": "d8227d40-4e8b-4b7f-baf4-52bb8a051e26",
    "fileName": "snickers-haz-cheeseburger.jpeg"
  },
  "breed": {
    "resourceUri": "http://localhost:8080/restexample/v1/catbreeds/Maine%20Coon",
    "name": "Maine Coon"
  }
}

Asset support​

A new expansion resource rest-assets-expanders was introduced which provides a default implementation for file links when they are represented by linkfields to assets:Asset. This includes an implementation for the upload and download endpoints. The rest-assets-expanders resource is now also part of the rest-jaxrs-stack resource.

Client aborts​

To round out support for files, the REST expanders now handle aborts for file uploads and downloads from the client. The API now returns nothing when these events occur rather than an error. A message will be logged on the server.

Strict finders​

There was a long-standing issue in the backend implementation for the API where in a few places finders are used that do not use strict equality to match resource identifiers. This has now been resolved by adding support instead for the same finders, but using strict equality operators. A strict not-equal operator was also introduced for this purpose.

Though the old finders using Eq and Ne operators instead of Se and Sne operators are still supported, the strict operators are now considered default and the non-strict ones only as fallback if they are the only available.

CORS support​

The support for CORS handling in the CorsFilterProvider class has been improved to now include the Access-Control-Expose-Headers, in order to whitelist headers returned by the server for use in scripts. New anchors exposed-headers are available to add additional headers if needed.

Better ValueType support​

While rest-expanders already provided support for ValueTypes, the AddDefaultRestApi transmutation still provisioned the model using the deprecated ValueFieldTypes. This has now been updated to correctly provision the model with ValueTypes instead.

Changes and improvements​

Migrating to QuerySearch metamodel​

Since version 3.x of rest-expanders, which was released just over a year ago, rest-expanders has integrated with querysearch-expanders by using the QuerySearch metamodel. This was introduced in such a way that it was 100% backwards compatible and also added to the model when expanding implicitly, so no change could really be observed from the perspective of an application developer.

Today the QuerySearch metamodel has matured to the point that what currently exists of the model is stable and will no longer have any big structural changes that are not additive. So with this version of rest-expanders, the implicitly added model will be removed. This means that it has to be defined in the model by the developer and coupled to the rest-expanders using the relevant jaxrs.querySearch option that has been implicitly used for quite some time.

The transmuters to add default REST APIs to the model have been modified to do this automatically, so in that sense, there will be no change to the way of interacting with rest-expanders in the majority of cases.

DataCommand options​

In rest-expanders version 3.8.0, options were introduced to mark the DataCommands that are to be used for the CRUD operations in the REST API. Starting with this version, the validation to check if this has been migrated has been removed, as well as them being implicitly added to the model. We assume that every project has been migrated by now, but this will be the last version where the Upgrade transmutation for rest-expanders does this migration automatically.

Changes and improvements​

Refactoring Options.Option​

As net.democritus.sys.Options.Option is being phased out, this version of rest-expanders replaced the vast majority of its uses with java.util.Optional. All of these changes are located in the validation system and may affect custom code.

Changes and improvements​

OpenApi 3.0 support​

In this version of rest-expanders, we've introduced support for OpenAPI 3.0. Previously we only supported OpenAPI 2.0, which was Swagger originally. Due to some technical challenges, we were not able to support OpenAPI 3.0 up to this point. Now that these hurdles have been cleared, we've finished the implementation and made it the new default.

The new version of the specification is also integrated with a Swagger UI front-end as was the case with the previous specification. This version does rely on a new major version of the Swagger library, which brings many breaking changes. As a regular, custom code will be heavily impacted by this change. We do provide a model option to switch back to OpenAPI 2.

More information about updating can be found in the migration guide.

SecurityRight annotation​

The SecurityRight annotation is used to define rights for an endpoint. Previously these would only be added to expanded endpoints when use of account::DataAccess was enabled. This made it difficult to add more functionality to the annotation. Now this annotation is added to all expanded endpoints and anchors are available in the annotation to add additional property values.

Changes and improvements​

UniqueConstraints​

This version of rest-expanders introduces initial support for the new UniqueConstraints added to the elements model. Though at this time the isUnique option will not yet be replaced by these constraints, if they are added to the model and fail validation, they will be correctly mapped to unique constraint validation errors in the REST API.

Known issues​

• This release breaks the DiagnosticInterceptor interface. This can affect implementations of the class in custom code that override the intercept(Diagnostic) method that was removed. Version 3.8.0 has a fix for backwards compatibility, though refactoring the custom class would be the preferred solution.

Migration guide​

This version of the expanders provides an update of Swagger UI from 3.52.5 to 4.15.5. One notable change is that all inline JavaScript and CSS styling was moved from the main swagger-ui.html file into separate files swagger-initializer.js and index.css. The CSS file has simply been added as css/swagger-ui-index.css. The inline JavaScript code did however contain several anchors. These anchors have been moved from their original location in html/<componentName>-swagger.html to js/<componentName>-swagger-initializer.js. This pertains to the following anchors:

• @before-setup and custom-before-setup
• @config and custom-config
• @after-setup and custom-after-setup

As all of these anchors were placed in inline javascript code, it should be sufficient move the harvest file from html/<componentName>-swagger.html.harvest to js/<componentName>-swagger-initializer.js.harvest.

Of course any expanders that may target these anchors will also have to be updated to inject features into the new file.

Version 3 of the REST Expanders bundle brings quite a few new features and improvements! This post will cover an overview of what's new and provide a migration guide to assist in updating. The full release notes can be found here.

Resources​

The expansion resources below provide REST Expanders 3.0.0.

Changes and improvements​

Java 17​

The REST Expanders have fully embraced Java 17! The expanders now require JRE 17 to run, as they now target Java 17 bytecode when building. Aside from the expanders, also the code they generate will now also require a Java 17 target. This means that you can expect Java 17 specific to start appearing in expanded applications!

Transmutations & Validations​

With the introduction of model transmutations and validations validations, the REST Expanders now provide their own transmuters and validations to support the development process.

Transmutations​

There are two transmutations available, which can provision a model with the required elements and option to expose a default JAX-RS REST API:

• On elements::Component, the transmutation CreateDefaultRestApi can be used to provision a Component and all of its DataElements a default API.

  mvn expanders:transmute-model -Dtransmutation=CreateDefaultRestApi -DtargetElement=componentName
  
• On elements::DataElement, the transmutation AddDefaultRestApi can be used to provision a single DataElement with a default API, given that its component has the option enableJaxrs.

  mvn expanders:transmute-model -Dtransmutation=AddDefaultRestApi -DtargetElement=componentName::dataElementName
  

The transmutations are also accessible in the context menus in the µRadiant and take into account modifications to the provisioned elements and options where possible.

Validations​

There are 5 new model validations that check for common mistakes made when using the options for the REST Expanders. More will be added in the future, but these will already cover quite a few issues.

Removed generated PATCH annotation​

To annotate PATCH methods in the REST API, the expanders used the io.swagger.jaxrs.PATCH annotation, which is part of the Swagger library. The reason for using this, is that the JAX-RS libraries did not include this by default, since PATCH was a later addition to the HTTP standard.

Using this annotation caused an issue, as it is part of the Swagger libraries, creating an unwanted coupling, as well as an issue when the enableSwagger option was not used. To resolve this, a new expanded annotation was added as <componentName>.jaxrs.method.PATCH, which is referenced when the option enableSwagger is not used.

Recent versions of JAX-RS now include the annotation javax.ws.rs.PATCH, just like the annotations for other default HTTP methods. Therefor all dependencies on both the Swagger PATCH annotation, as well as the generated one have been replaced. As this deprecates the generated annotation, this has also been removed from the expanders.

To update custom code that uses either annotation, simply replace the import with javax.ws.rs.PATCH.

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.

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.

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.

Paging parameters​

The DEFAULT_PAGE and DEFAULT_PAGE_SIZE constants could previously be modified using the anchors custom-default-page and custom-default-page-size. These anchors have been dropped in favor of DataOptions jaxrs.endpoint.getList.defaultPage and jaxrs.endpoint.getList.defaultPageSize.