REST Expanders 4.26.0

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.

Resource	Version
rest-jaxrs-stack	4.30.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.

Example

In this resource a file link is represented by the birthCertificate. As there's a download endpoint for the field, the resource also returns a resourceUri with a link to the download endpoint for that specific file 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.

Migration guide

Migrating to strict finders

While still backwards compatible with the old non-strict finders, it is recommended to update to strict finders. The upgrade transmutation has been amended to provide a migration for this. Since there's a good chance of the regular equals finders being used in the Knockout UI by end-users, these will not be removed. Rather, if these are available, the equivalent finders with Se operator will be added as a second finder with the option noViewLayer, since these would have the same description in the Knockout UI.

We assume that the findByFieldEq_KeyNe were added specifically for the REST API, given that they have a rather unique structure. So these are replaced by the equivalent findByFieldSe_KeySne finders.

In µRadiant, run the "Upgrade Rest Expanders Model" transmutation on the Application model:

On command-line, you can execute the transmutation as:

mvn expanders:transmute-model -Dtransmutation=UpgradeRestExpandersModel -DtargetElement=applicationName::applicationVersion