ADR-007: File-Based API Response Cache

Decision Analysis and Resolution: REST API Response Caching

Created by: SW360 Architecture Team
Original Decision: 2026
Reformatted: April 2026
Status: Accepted
Estimated read time: 12 minutes

Table of Contents

1. Background
2. Goal
3. Key Principles
4. Key Inputs, Assumptions and Restrictions
5. Options Analysis
   • Option 1 - Spring @Cacheable (In-Memory)
   • Option 2 - Redis/External Cache
   • Option 3 - File-Based Response Cache
   • Option 4 - No Caching (Status Quo)
6. Criteria for Making a Decision
7. Final Decision
8. Implementation Details
9. Contributors

Background

The SW360 REST API exposes resource-intensive endpoints that aggregate large amounts of data. The most critical example is GET /releases?allDetails=true, which:

• Takes 3-5 minutes to complete, fetching and serializing thousands of releases with full details
• Causes server resource competition when multiple concurrent requests are made
• Can lead to server degradation or crashes requiring restarts
• Impacts user experience significantly for common use cases like exporting data

Production Incidents:

• Multiple concurrent allDetails=true requests have caused OutOfMemory errors
• Server restarts required during high-usage periods
• Users experience timeouts and abandoned requests

Why This Decision Matters: API performance directly affects user productivity and system stability. Without caching, every request pays the full computational cost.

Goal

The goal of this decision analysis is to:

1. Dramatically reduce response time for expensive API endpoints
2. Prevent server resource exhaustion from concurrent requests
3. Maintain data consistency expectations
4. Provide visibility into cache state for operations
5. Enable opt-in adoption (disabled by default)

Key Principles

Key Inputs, Assumptions and Restrictions

Options Analysis

Option 1 - Spring @Cacheable (In-Memory)

Summary

Use Spring’s built-in caching abstraction with annotations like @Cacheable. Cache the Java objects in JVM heap memory using providers like Caffeine or EhCache.

Conceptual View

graph TB
    subgraph SC["Spring @Cacheable"]
        direction TB
        A1["@Cacheable('releases')<br/>public List getAllReleases() { ... }"]
        A2["Cache Storage: JVM Heap Memory"]
        A3["Entry: Serialized Java objects (100-500 MB)"]
        A4["⚠️ Risk: OutOfMemoryError"]
    end

Impact / Changes Required

• Add @Cacheable annotations to controller methods
• Configure cache provider (Caffeine/EhCache)
• Implement cache eviction on data mutations
• Monitor heap usage carefully

SWOT Analysis

Option 2 - Redis/External Cache

Summary

Use Redis or another external caching system to store serialized responses. The cache lives outside the JVM, survives restarts, and can be shared across multiple instances.

Conceptual View

graph LR
    A[SW360 REST<br/>Instance 1] --> B[Redis Cache]
    C[SW360 REST<br/>Instance 2] --> B

Impact / Changes Required

• Deploy and configure Redis cluster
• Add Redis client dependency
• Implement serialization layer
• Configure network connectivity
• Handle Redis availability

SWOT Analysis

Option 3 - File-Based Response Cache

Summary

Cache pre-serialized JSON responses to disk files. Serve cached responses directly from disk without JVM heap involvement. Separate cache files per user role for security.

Conceptual View

graph TB
    subgraph FBC["File-Based Response Cache"]
        direction TB
        R["GET /releases?allDetails=true (ADMIN)"]
        R --> F["CacheReadFilter (Servlet Filter)"]
        F --> V["Resolve variant: ADMIN (from JWT)"]
        V --> CHK{"Check cache file"}
        CHK -->|HIT| S["Stream file to response (~10ms)"]
        CHK -->|MISS| C["Proceed to controller (3-5 min)"]
        FILES["Cache Files:<br/>/cache/releases-all-details-ADMIN.json (150 MB)<br/>/cache/releases-all-details-USER.json (120 MB)<br/>/cache/releases-all-details-CLEARING.json (140 MB)"]
    end

Impact / Changes Required

• Implement servlet filter for cache reads
• Implement ResponseBodyAdvice for cache writes
• Create cache management infrastructure
• Add admin endpoints for monitoring/invalidation
• Configure disk space allocation

SWOT Analysis

Option 4 - No Caching (Status Quo)

Summary

Continue without API response caching. Every request fully executes the controller logic and generates the complete response.

Conceptual View

graph TB
    subgraph NC["No Caching (Status Quo)"]
        direction TB
        N1["Every request: 3-5 minutes"]
        N2["Concurrent requests: Resource competition"]
        N3["Peak load: Server degradation/crashes"]
    end

Impact / Changes Required

• No changes
• Accept current performance limitations
• Document workarounds for users

SWOT Analysis

Criteria for Making a Decision

T-Shirt Sizing Scale

Weighted Evaluation Matrix

Score Summary

Final Decision

Selected Option: File-Based Response Cache

Rationale

File-based caching was selected based on:

1. Highest Weighted Score (733.75) - Best fit for SW360’s requirements

2. Memory Safety (XL) - Critical advantage:

   • Large responses streamed directly from disk
   • No JVM heap involvement
   • Eliminates OOM risk that exists with in-memory caching

3. No External Dependencies (XL) - Self-contained:

   • No Redis/Memcached infrastructure required
   • Simpler operational model
   • Suitable for single-instance deployments

4. Role-Based Variants (XL) - Security maintained:

   • Separate cache files per UserGroup (ADMIN, USER, etc.)
   • Different users get appropriate filtered data
   • No security leakage between roles

5. Large Response Handling (XL) - Designed for the problem:

   • 100-500 MB responses handled efficiently
   • Disk I/O is optimized for streaming
   • No serialization overhead on cache hits

Implementation Details

Architecture

graph TB
    A["GET /api/releases?allDetails=true (as ADMIN)"] --> B["CacheReadFilter (Servlet Filter)"]
    B --> C["Resolve variant: ADMIN (from JWT)"]
    C --> D{"Check cache:<br/>releases-all-details-ADMIN.json"}
    D -->|HIT| E["Stream JSON from disk (~10-50ms)"]
    D -->|MISS| F["ReleaseController.getReleasesForUser()"]
    F --> G["Execute business logic (3-5 minutes)"]
    G --> H["CachedResponseBodyAdvice.beforeBodyWrite()"]
    H --> I["Serialize response to JSON"]
    I --> J["Write to cache file (async)"]
    J --> K["Response sent"]
    E --> K

Key Components

Configuration

# Global settings
rest.cache.enabled=true
rest.cache.directory=/var/sw360/cache

# Per-endpoint settings
rest.cache.releases-all-details.enabled=true
rest.cache.releases-all-details.ttl.seconds=86400
rest.cache.releases-all-details.max.stale.seconds=300
rest.cache.releases-all-details.per.role.caching=true

Admin API

Contributors

Consequences Summary

Positive

• ✅ Performance—cache hits served in ~10-50ms vs 3-5 minutes
• ✅ Stability—no resource competition from concurrent requests
• ✅ Memory safety—no risk of OOM from large cached responses
• ✅ Persistence—cache survives application restarts
• ✅ Visibility—per-variant statistics for monitoring
• ✅ Security—per-role caching ensures appropriate data access
• ✅ Extensibility—easy to add new cached endpoints

Negative

• ⚠️ Disk usage—cache files consume disk space
• ⚠️ Stale data—cache may serve stale data until TTL/invalidation
• ⚠️ Single-instance—not shared across clustered deployments
• ⚠️ Complexity—additional components to understand

Neutral

• Automatic invalidation on data mutations (POST/PATCH/DELETE)
• Filtered requests (with query params) not cached
• Feature disabled by default (opt-in)

Revision History