Spring Data offset-based paging

This version adds a new library that implements support for offset-based pagination when using Spring Data. This library is released as part of the SimplyRESTful framework but doesn't require SimplyRESTful itself.

Bugfixes for new filter

This release fixes some bugs in the filter that modifies the Accept header.

Support both plain JSON and HAL+JSON

This release provides full support for representing all resources as either plain JSON with a custom JSON media type or HAL+JSON with a custom profile parameter on the HAL+JSON media type. By default, the plain JSON representation is returned, as this should be more familiar to API consumers. The HAL+JSON representation can be requested through the Accept header, using standard HTTP Content Negotiation. The HAL+JSON representation is recommended for more advanced use of the API as it provides more consistency in the structure of the representation.

This release also provides a filter that allows using application/json in the Accept header to match against any other +json suffixed media type. This allows an API consumer to simply specify application/json in the Accept header in order to get the plain JSON representation. Since this representation uses a custom media type, with the +json suffix, it is not considered compatible with application/json (in native Java code). So if the API consumer were to specify application/json in the Accept header without this filter enabled in the API, the API would return a 406 error. This filter is enabled by default in the convenience deploy libraries.

Default v2 collection and deprecated client.

The API will now return the v2 collection by default, specifically the plain JSON v2 collection. When the Accept header contains application/hal+json without any profile, the HAL+JSON v2 collection will be returned. The HAL+JSON v1 collection will only returned when specifically requested. If you wish to change this behaviour, you can still override the JAX-RS method from the interface and modify the JAX-RS annotations. You will need to copy all JAX-RS annotations from the interface for this to work correctly.

The client library is now deprecated. This will be replaced in the future with an implementation that works according to the Rest Client 2.0 standard.

A PUT request to the resource URI will no longer allow creating a new resource. It will return a 404 Not Found error instead. While such behaviour is technically allowed according to the HTTP specification, this does not match the expectation for a REST API.

Improved customizability

The JAX-RS Web Resource features are now separated into their own interface classes. This allows you to pick and choose which features you want to include in your own Web Resource (aka endpoint class), like retrieving the collection of resources or deleting a single resource. There is still a default Web Resource available that contains the default set of functionality. Notably missing from this default set is the new feature to allow streaming resources using server-sent events (SSE). This feature can easily be added to any Web Resource by also having it implement the corresponding interface class which provides the default implementation for it.

Aside from some smaller fixes and improvements (including more testing), this release also includes a (still experimental) filter for the fields query parameter. This can automatically filter on any of the fields in any JSON-based response, using a dot-notation to indicate the hierarchy of fields. It has to be registered as a servlet filter.

Also, the previously deprecated persist-springdata dependency is now removed entirely.

Another fix for UriCustomizer

This minor release contains a bugfix for the UriCustomizer which caused the service document (at the root of the API) to no longer be found (responding with 404 Not Found). This is now fixed and covered by the automated tests.

Fix for UriCustomizer

This minor release contains a bugfix for the new UriCustomizer filter. This functionality is now also covered by the automated tests.

OpenAPI v3, HTTP/2 and more

Updated dependencies

The framework has been refactored and now generates and uses OpenAPI v3 (swagger 2.x) Specification documents.
The javax.* dependencies have also been migrated to the newer jakarta.* dependencies that replace them.

HTTP/2 for Tomcat

Allows the Tomcat server running the API to upgrade to the HTTP/2 protocol. This does not require SSL/TLS to be enabled on the API, as is the case with Jetty (HTTP/2 is not enabled for Jetty in the framework).

Separate JAX-RS providers for JSON and HAL+JSON

This allows the API to produce responses in either media type, as needed. Previously, all JSON responses would be rewritten in HAL+JSON format.

There is a caveat with this functionality, related to the generated OpenAPI Specification document. If a resource is provided in both JSON and HAL+JSON format, the OpenAPI Specification will only include the definition for that resource in the HAL-based format. It will not have a separate definition for the JSON-based format, even though the JSON-based response specification has its own reference to the definition.

A JAX-RS filter that uses an HTTP header as source for the request URI

This allows the API to generate links using that URI instead of the one detected by the JAX-RS framework. For example, when using a reverse proxy, the URI that the API consumer uses will be different from the one the JAX-RS framework knows.

To use this, add a property or environment variable with the name simplyrestful.uri.http.header and the relevant HTTP header name as value. For example, add simplyrestful.uri.http.header=X-Original-URL when using a reverse proxy to ensure that the user-visible URI is used to modify and generate links in the API.

Backwards Compatibility

To ensure a smooth migration, the media type priorities for the Collection have been changed. The default media type will be v1, meaning the previous Collection resource. You can get the new Collection resource (v2) by specifying the media type in the Accept header, either application/hal+json; profile="https://arucard21.github.io/SimplyRESTful-Framework/HALCollection/v2" for the HAL-based resource or application/x.simplyrestful-halcollection-v2+json for the plain JSON-based resource.

In a future release, the default will be changed to the HAL-based v2 Collection resource.

Bugfix

Add and register JacksonHALJsonProvider as JAX-RS filter. This is essentially the same as JacksonJsonProvider but with annotations that configure it to only be used for HAL+JSON content. This allows the JacksonJsonProvider, with a normal ObjectMapper, to exist next to this new JacksonHALJsonProvider which uses HALMapper instead (provided through HALMapperProvider). The JAX-RS framework will then be able to correctly serialize and deserialize both JSON and HAL+JSON content automatically.