Cache HTTP responses with local fallback

Applies to: Molca Core

Overview

This recipe shows how to make HTTP API calls with local caching for offline fallback. You’ll create an HttpRequestAsset, fetch data asynchronously, cache responses locally via PlayerPrefs, and serve stale cache when the network is unavailable. For a proper cache subsystem with TTL, group tagging, and disk storage, use CacheManager instead of raw PlayerPrefs.

Prerequisites

SDK modules: Molca Core installed
Unity setup: RuntimeManager configured in your scene
Prior knowledge: HttpClient, Dependency injection
Recommended: Understanding of C# async/await patterns

Step-by-step

Step 1: Create HttpRequest ScriptableObject

Create an HttpRequestAsset to define your API endpoint configuration. This makes the request reusable and configurable in the Inspector.

// In the Unity Editor:
// 1. Right-click in Project window → Create → Molca → Networking → HTTP Request
// 2. Name it "FetchUserProfileRequest"
// 3. Configure in Inspector:
//    - URL: "/api/user/profile"
//    - Method: GET
//    - Headers: Add "Accept: application/json"
//    - Timeout: 10 seconds

Why this works: HttpRequestAsset is a ScriptableObject that encapsulates endpoint configuration (URL, method, headers, body templates). This separates configuration from code and makes it easy to modify endpoints without recompiling.

Step 2: Build the complete caching service

Create a service component that fetches from the API, caches locally, handles staleness, and falls back to cached data on errors.

using UnityEngine;
using Molca;
using Molca.Networking.Http;
using Molca.Events;
using System;

[Serializable]
public class UserProfile
{
    public string userId;
    public string username;
    public string email;
    public int level;
    public long lastLoginTimestamp;
}

public class UserProfileService : MonoBehaviour
{
    [Header("HTTP Configuration")]
    [SerializeField] private HttpRequestAsset fetchProfileRequest;
    
    [Header("Cache Configuration")]
    [SerializeField] private float cacheValiditySeconds = 300f;
    
    [Header("Events")]
    [Inject] private EventDispatcher _eventDispatcher;
    
    private const string PROFILE_KEY = "UserProfile";
    private const string TIMESTAMP_KEY = "UserProfile_Timestamp";
    
    private UserProfile _currentProfile;

    private async void Start()
    {
        await RuntimeManager.WaitForInitialization();
        
        // Serve cached data immediately, refresh in background
        if (LoadCachedProfile())
        {
            Debug.Log($"Cached profile: {_currentProfile.username}");
            if (!IsCacheValid())
                await FetchAndCache();
        }
        else
        {
            await FetchAndCache();
        }
    }

    private async System.Threading.Tasks.Task FetchAndCache()
    {
        try
        {
            var response = await fetchProfileRequest.SendAsync();
            if (!response.IsSuccess) { FallbackToCache(); return; }
            
            _currentProfile = JsonUtility.FromJson<UserProfile>(response.Text);
            if (_currentProfile == null) { FallbackToCache(); return; }
            
            // Cache with timestamp
            PlayerPrefs.SetString(PROFILE_KEY, response.Text);
            PlayerPrefs.SetString(TIMESTAMP_KEY, 
                DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString());
            PlayerPrefs.Save();
        }
        catch (Exception ex)
        {
            Debug.LogWarning($"Fetch failed: {ex.Message}");
            FallbackToCache();
        }
    }

    private void FallbackToCache()
    {
        if (!LoadCachedProfile())
            Debug.LogError("No cached data available");
    }

    private bool LoadCachedProfile()
    {
        if (!PlayerPrefs.HasKey(PROFILE_KEY)) return false;
        _currentProfile = JsonUtility.FromJson<UserProfile>(
            PlayerPrefs.GetString(PROFILE_KEY));
        return _currentProfile != null;
    }

    private bool IsCacheValid()
    {
        if (!PlayerPrefs.HasKey(TIMESTAMP_KEY)) return false;
        long age = DateTimeOffset.UtcNow.ToUnixTimeSeconds() 
            - long.Parse(PlayerPrefs.GetString(TIMESTAMP_KEY));
        return age < cacheValiditySeconds;
    }

    public void ForceRefresh() => _ = FetchAndCache();
}

Why this works: The “cache-first” pattern loads locally stored data instantly for UI responsiveness, then refreshes from the network in the background. On fetch failure, stale cache is used as fallback — graceful degradation instead of an error state. The service class in Step 2 above is the complete implementation. For CacheManager-based caching, see CacheManager.

Troubleshooting

HTTP request fails with “BaseUrl not set”: Configure the HttpModule in Global Settings with your API base URL. Alternatively, set useFullUrl = true on the HttpRequestAsset and provide the complete URL.
JSON parsing fails: Verify that your C# data structure matches the API response format exactly. Field names must match (case-sensitive). Use [SerializeField] for private fields or make fields public. For complex JSON, consider using Newtonsoft.Json instead of JsonUtility.
Cached data not persisting between sessions: Ensure you call PlayerPrefs.Save() after setting values. On some platforms, PlayerPrefs may not persist immediately without explicit save. For more robust persistence, consider using DataManager with a custom data provider.
Cache never invalidates: Verify that cacheValiditySeconds is set to a reasonable value. Check that the timestamp is being saved correctly. Use Debug.Log to print cache age and validity checks.
Profile loads but events don’t fire: Ensure EventDispatcher is injected successfully. Call await RuntimeManager.WaitForInitialization() before dispatching events. Verify that subscribers are registered before the event is dispatched.
Multiple simultaneous fetches: The _isFetching flag prevents concurrent requests. If you need to queue requests, implement a request queue or use DataManager’s built-in queuing.

HttpClient — async HTTP requests and ScriptableObject endpoints
DataManager — data providers, caching, and model subscriptions
Dependency injection — injecting HttpClient and DataManager services
EventDispatcher — notifying other systems when data is loaded
Recipe: Create and dispatch custom events — using EventDispatcher for notifications

Overview

Common Tasks

Molca Core

Shared module (MolcaSDK)

Molca SDK - VR

Molca SDK - DT

Cache HTTP responses with local fallback

Overview

Prerequisites

Step-by-step

Step 1: Create HttpRequest ScriptableObject

Step 2: Build the complete caching service

Troubleshooting

​Overview

​Prerequisites

​Step-by-step

​Step 1: Create HttpRequest ScriptableObject

​Step 2: Build the complete caching service

​Troubleshooting

​Related

Overview

Prerequisites

Step-by-step

Step 1: Create HttpRequest ScriptableObject

Step 2: Build the complete caching service

Troubleshooting

Related