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.

Fixes for OpenAPI Specification

This release includes some fixes for generation the OpenAPI Specification document. In particular, it removes some of the annotations from this framework to allow Swagger to auto-generate those sections from the API implementation that uses this framework. This should result in more accurate information.

Improve OpenAPI documentation

This release contains several fixes that should improve the generated OpenAPI Specification document. The Jersey example is also updated to add the remaining annotations to get a fully functional document and shows how to include Swagger UI with your API.

In addition, HALCollectionV2's media type now has a parameter to indicate the type of resource it contains, called item-type.

Legacy behavior fixed

This release mainly fixes the behavior of the legacy implementation for collections. This now returns HALCollectionV1 by default as it did before. This ensures that the legacy implementation works the same as before.

Remove parameters from self links in collection

This release ensures that the self link on items in a collection do not contain the query parameters used when accessing the collection. This occurs because the URL used to access the collection needs to be used to build the self link. So these extra parameters need to be removed. This bugfix only does this for the self link. Any other links that are introduced by an API using this framework will likely also run into this problem and will similarly have to remove those query parameters themselves. SimplyRESTful has no control over how those additional links are created so it cannot remove those query parameters.

This is a small bugfix and should be a patch version update. But the last release, which contained a breaking change, was incorrectly created as a patch version update instead of a minor version update. Because of that, I'm doing a minor version update with this bugfix.

HALCollectionV1 removed

This release removes support for the deprecated HALCollectionV1 from the default implementation. It is still available through the LegacyCollectionGet interface that you would have to explicitly use. It cannot be used together with DefaultCollectionGet (which is also used through DefaultWebResource). For now, the legacy implementation mostly corresponds to the previous default implementation. But the current default implementation, which only supports HALCollectionV2, will continue to receive updates and improvements which the legacy implementation will not. And at some point in the future, this legacy implementation will also be removed.

This release also includes some bugfixes.

• The Java client now uses the fields and sort query parameters correctly.
• The JSON fields servlet filter now parses JSON as UTF-8 and handles characters that are larger than 1 byte correctly

Note: This release contains a breaking change and was incorrectly released as a patch version upgrade.

Fix for custom errors

This is a quick fix for the new custom errors in the TypeScript client. These errors were not exported so they could not be used yet, which would be necessary for checking their type. With this release, the errors are now correctly exported.