3.2.20200419165537

Version: 3.2.20200419165537

Documentation (pdf)

This release provides many incremental improvements over 3.1 together with experimental support for versioning and more support for the upcoming JSON:API 1.1.

Versioning Support (experimental) #238

This release brings experimental support for versioning of resources and fields based on content negotiation. Any resource and field can carry a version range to specify its availability. Crnk will disregard any resource and field with a version range that does not intersect with the request version. The HTTP Accept header is used to pass along the desired version as part of general content negotiation. This has the benefit that URLs remain constant across versions, greatly simplifying usability and linking. For a more detailed discussion, see here[https://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation/]. An example looks like:

@JsonApiResource(type = "versionedTask")
@JsonApiVersion(max = 5)
public class VersionedTask {

    public enum CompletionStatus {
        DONE,
        OPEN,
        IN_PROGRESS
    }

    @JsonApiId
    private Long id;

    private String name;

    @JsonApiVersion(min = 1, max = 3)
    private boolean completed;

    @JsonApiVersion(min = 5)
    @JsonProperty("completed")
    private CompletionStatus newCompleted;

}

For more details have a look here.

Support for Object-based Links

Links can be represented as either simple string or structured objects with href, rel, anchor, params, describedBy and meta. There is a new Link interface and DefaultLink implementation to model such objects. LinksInformation can now either hold Strings or DefaultLink. An example looks like:

"links": {
	"self": "http://example.com/articles/1/relationships/comments",
	"related": {
		"href": "http://example.com/articles/1/comments",
		"describedby": "http://example.com/schemas/article-comments",
		"meta": {
			"count": 10
		}
	}
}

More information can be found in https://jsonapi.org/format/1.1/#document-resource-object-links and http://www.crnk.io/releases/latest/documentation/#_jsonapilinksinformation.

Misc Improvements

• Improved logging for relationship inclusion mechanism. Set io.crnk to DEBUG to learn more about how inclusions are loaded.
• Re-enabled Spring Boot 1 support upon request to be maintained a little while longer.
• JSON-based filter parameters fixed to support renaming of attributes with @JsonProperty.
• When using faceted search, the value map is sorted by total count in descending order.
• Built-in ExceptionMappers can be overridden by custom ones by implementing the Prioritizable interface.
• ExceptionMappers can implement Prioritizable
• More documentation for ExceptionMappers
• Meta-model is excluded from OpenAPI generation by default. #625
• Non-ID fields can no longer be named id.
• Bulk support through the BulkResourceRepository interface now supports HTTP DELETE operations. This complements existing support for POST. PATCH has not yet been implemented.
• JPA repositories avoid issuing a count query in some situations where the configured offset, limit and received result sets allow to by-pass it. Greatly improving performance in some situations! Where every bit of performance is essential, the existing "has more" strategy rather than total count may also be of help.
• JAX-RS integration has an improved path handling. There will be some more work to harden this area in the future to account for the different behavior of different frameworks.
• Refinements to the JPA-related documentation. For example, how to implement more advanced use cases where the entity and resource model do not fully match.
• Better error message when the parsing of an enum parameter fails.
• The order of attributes is honored in the serialized REST documents. Attributes in the implementation and on the REST layer will have the same order.
• A bug fix when resolving attribute paths from subtypes of a resource #712.
• Improvements to the Typescript generation for the java.util.Map data type #709
• The CrnkExceptionMapper uses the JSON:API error fields title and code if detail is not available for better error messages.
• New UrlBuilder interface introduced as public API that allows to customize the construction of URLs out of resource ids and QuerySpecs.

Acknowledgements

A special thanks to Broad, Ralph, JB, PoffM, Christian, Sebastian, Kokogino, duncanportelli, Luka, Gianin, fjf2002, Tomasz, erjaimin for all the contributions to make this release happen!