Release 1.5.0: Cache Support for Compound Documents

[MoonWorm]

Overview

This release adds built-in caching to the Compound Documents Resolver, reducing redundant downstream HTTP calls and improving response times for repeated include queries.

How It Works

The resolver now caches individual resources by their type, id, requested includes, and sparse fields. When a compound document request arrives, the resolver checks the cache first and only fetches cache misses via HTTP - cached and freshly fetched resources are merged transparently.

Cache behavior is driven by standard HTTP Cache-Control headers from downstream responses:

• max-age / s-maxage determines entry TTL
• no-store, no-cache, private prevent caching entirely

The final compound document response carries an aggregated Cache-Control header - the most restrictive directive across all included resources. For example, if countries returns max-age=300 and currencies returns max-age=60, the compound document response will contain max-age=60.

Configuration

Cache is enabled by default. To customize:

jsonapi4j:
  cd:
    cache:
      enabled: true   # default: true
      maxSize: 1000   # default: 1000, soft cap with LRU eviction

Custom Cache Implementations

The built-in cache uses an in-memory ConcurrentHashMap with lazy TTL expiration and LRU eviction. For distributed deployments or custom eviction policies, implement the CompoundDocsResourceCache SPI and register your own bean - the framework will use it instead of the default.

Resources

• Release notes: https://github.com/MoonWorm/jsonapi4j/releases/tag/v1.5.0
• Documentation: https://api4.pro/