Support Java records for API resources (breaking change)

This version introduces full support for using Java records as API resources. You can now create your API resources as Java records that implement the ApiResource interface.

In order to support immutable records as API resources, the framework will no longer try to automatically fix the self links. Instead, the framework will throw an error if the self link is invalid. Notably, when creating a resource, the API now requires that the self link is not included. And when implementing the create() method, the resource that is returned is now required to include the self link with the correct absolute URL to itself.

Since this behavior is a breaking change already, an additional breaking change was included. The UUID of the resource was previously provided to by the framework to the underlying implementation. This is no longer the case. Since the self link must now be handled by the implementation anyway, it would be better to get the UUID from that self link directly. There is a convenience method for this in WebResourceUtils called parseUuidFromLastSegmentOfUri(URI resourceUri) that simply converts the last segment of the path into a UUID.

Support Java records for API resources (incomplete)

This version introduces support for using Java records as API resources. However, the implementation was found to be incomplete after publishing so this version should not be used. Use version 2.3.0 instead.

Improve Java compatibility

Improve the Java compatibility by configuring the Java version to 17 instead of 21.
Dependencies have also been updated but there should not be any breaking changes.

Sort improvement

Allow multiple fields to be defined in a single sort query parameter.

Improve resources discoverability

Make all JAX-RS resources discoverable for both CDI and JAX-RS.

Breaking changes

This is a major version release since it includes several breaking changes. Functionally, not much has changed but these breaking changes were needed on a technical level to improve the code quality. Most of the other changes focus on improving the OpenAPI annotations to generate a better OpenAPI Specification document.

With this release, the repo also includes an example API that adheres to the NLGov REST API Design Rules (ADR). The ADR provides a linter and validator to test some of these rules and the results and evaluation is documented in the readme of this example API. Most of the OpenAPI-related improvements in this release were inspired by the insights provided when validating this example API against the ADR.

Breaking changes

• Rename classes to fully conform to PascalCase.
• Change PUT implementation to return 204 instead of 200 on success since it contains no body.
• Update Java client to accept 204 as status code for a PUT request, matching the change to the server-side implementation.
• Remove unused method parameters from the default implementations provided by the framework.
• Consolidate all JAX-RS Providers in the jaxrs-providers package. This makes these JAX-RS providers more reusable for any other JAX-RS API.
• Allow for an IOException when an outbound Server-Sent Events stream is closed. This was needed in the updated version.
• Removed deploy-jetty-cxf (along with its example API), deploy-springboot-cxf (along with its example API), and fields-filter-json-servlet from the repo since they were unused and had become outdated.
• Remove the override mechanism from the JSON fields filter, instead using the known default value for the fields parameter only when an ApiCollection resource is requested. Any other JSON response will be unfiltered by default so the fields parameter would need to be explicitly provided. This covers what the override mechanism was intended for with a simpler implementation.
• Removed the use of ResourceInfo as injected context object. This is not its intended use according to the specification and not all JAX-RS frameworks make it available as such. Alternative methods have been provided to achieve similar functionality in WebResourceUtils.java.

Dependency updates

• Update Gradle and reconfigure to use jvm-test-suite plugin consistently
• Update Java to version 21 (latest LTS)
• Update dependencies, most notably updating JAX-RS (jakarta.ws.rs-api) to the next major version, 4.0.0.

Other changes

• Hide the service document from the OpenAPI Specification documentation
• Remove some OpenAPI annotations so they can be defined in child classes with more specific information than possible in the framework.
• Add some OpenAPI annotations to the default implementation where more specific information from child classes is not needed.
• The JSON fields filter output stream can only handle JSON documents up to a maximum size of 1MiB. This was increased from 8KiB since growing the buffer as needed didn't work correctly.

Support streaming API resources as server-sent events

This release adds support for sending API resources as server-sent events. This can be used as an alternative to paging when you want to get all API resources. It also add support for receiving those API resources in the client.

This works by having the API set up a one-directional connection to the client, then sending each API resource (in JSON format) over that connection. Once all API resources are sent, an event marking the end of the collection is sent and the connection is closed.

This functionality requires implementing the stream() functionality. It is also strongly recommended to use HTTP/2 due to limitations with the amount of connections that can be made in earlier versions of HTTP.

Aside from this, the JSON field filter has been improved. It can now be done through a JAX-RS filter, instead of a servlet filter. This was necessary in order to apply the JSON field filter on the server-sent events, allowing you to filter the fields of the API resources sent as events. The servlet filter is now deprecated and will be removed in the future.

Client bugfix

This release fixes an issue with the client where the OpenAPI Specification was retrieved by URL using the built-in functionality from the Swagger dependency. The client now uses the provided JAX-RS client, as it does for all other HTTP requests. This ensures that the OpenAPI Specification is retrieved according to the configuration provided for the JAX-RS client (which may include things like authentication headers).

This release also includes a minor server-side fix to set the correct media type in the API service document's link to the OpenAPI Specification (which was previously left as null).

OpenAPI fixes

This release mostly contains fixes for the OpenAPI Specification document that is generated. The schema for the Link object now matches how it should actually be used and the schemas for unused parent classes are removed.

This release also changes the behavior of JSON serialization and no longer hides empty or null fields. This can still be overridden by adding @JsonInclude(Include.NON_EMPTY) on the class where you want those fields hidden.

Migrate to Jakarta package names

This release updates the framework to Java 17 and the latest Jakarta EE dependencies that use the jakarta.* package name. This means that this update is a breaking change and entirely incompatible with previous versions.

In addition, the support for HAL+JSON is now removed. The reason for this is that JAX-RS currently does not differentiate media types based on their media type parameters, unlike with HTTP Content Negotiation. What this means, is that different HAL+JSON resources would not be seen as different by JAX-RS as their media type would only have a different value in the profile parameter. I have reported this to the Jakarta specification maintainers but they do not seem inclined to change this behavior. This framework contained several workaround to make this work anyway but this was never an optimal solution. The dependencies used for this workaround have also not been updated to the Jakarta package names so this is why support for HAL+JSON had to be removed now.

Migrating to this release is a breaking change but it should mostly only require trivial changes. The Jakarta packages need to be renamed from javax.* to jakarta.*. And any references to HALResource and HALCollection should be renamed to APIResource and APICollection, including when this is used in method names.