DEV Community: Neil

Caching a NetworkResponse from the dart http client using Hive

Neil — Thu, 06 Jan 2022 06:45:28 +0000

This article will be a continuation of my previous article where we explored Effective handover of api responses to your code in dart. If you haven't read it yet, I would suggest reading through it first so that you can have context into what will be discussed today.

NOTE: This was a great solution to our problem but won't necessarily be the best fit for what you need.

The Repository Pattern

Previously I highlighted that we use the Repository pattern to facilitate our ViewModels with a NetworkResponse containing information that comes back from the rest API call. Our repositories give us a neat connection with the REST client without seeing the guts of what it's made of and also allows us to build on top of it without disturbing the harmony of our REST client world.

When you hear the word repository your first thought might be "it's something that serves data to you from a stored location" and you would be right. According to the Merriam Webster dictionary a repository is

a place, room, or container where something is deposited or stored

If you think about it from a mobile perspective, ignoring any knowledge of the innards of a back-end, your REST client, where the Repository gets its data from, could fit into this description as it provides you with data stored in a specific location and would make sense to be used within a repository. But the Repository could be so much more than that without needing a name change. We could use it to fetch data from the REST service but also use it to improve our application performance by introducing a cache to it so that the data is retrieved from disk when certain criteria is met.

This is a well known pattern, not necessarily with the Repository pattern, but in http clients as a whole. One well known dart http client, Dio, has a plugin that also uses Hive as a disk cache and many others that also provide caching capabilities.

There was no caching to start with 😬

Here is some pretext into our problem before I go into the caching details, which the heading promised you, so that you can understand why we made the architectural decisions that we did.

Initially when our application was built the developers didn't see a need for a cache, financial services applications generally don't do that? So the repositories were built and the REST service endpoints were consumed but we soon realised that we desperately needed a cache seeing that almost every screen had a progress bar. We looked at the REST calls and found the data that was not prone to change as often as something like a transactions list, and took the opportunity to improve our application performance without needing to make drastic changes to the codebase.

The `NetworkCache` was born

As I mentioned in the previous article we use the dart http package to make our network calls. We decided to build our own network cache on top of the http client using Hive because of the security and speed that it promised.

Before we added caching our Repository method for fetching countries looked something like this.

Future<NetworkResponse<Countries, NetworkException>> getCountries() async {
  return makeRequest(() => mukuruRestClient.getCountries());
}

After attaching our NetworkCache to the call, the same method it ended up looking like this.

final NetworkCache networkCache = NetworkCache(registry: [
  CacheKey.countries,
]);

Future<NetworkResponse<Countries, NetworkException>> getCountries() async {
  return makeRequest(
    () => networkCache.getOrUpdate<Countries>(
      cacheKey: CacheKey.countries,
      networkRequest: () => mukuruRestClient.getCountries(),
      cachingStrategy: ExpiryCache(duration: Duration(days: 31)),
    ),
  );
}

This allowed us to cache some calls and omit caching for others without making changes to our existing codebase except for the repositories.

Let's dive on in

The cache requires us to define a specific key linked to the stored request and also a CachingStrategy, the default strategy is ExpiryCache. I included the cachingStrategy in the above example for the example's sake with a value other than 24 hours, generally it's omitted because we use 24 hours as our default.

Below is our implementation of the NetworkCache, if you're familiar with hive this should make some sense, if not you can read up on it here. In short a Box in Hive can be compared to a Table in SQL.

class NetworkCache {

  NetworkCache({
    required this.registry,
  });

  final List<String> registry;

  Future clear() async {
    var futures = <Future>[];
    for (String cacheKey in registry) {
      futures.add(Hive.openBox(cacheKey));
    }
    await Future.wait(futures);
    Hive.deleteFromDisk();
  }

  Future<T> getOrUpdate<T extends CacheItem>({
    required String cacheKey,
    required Function networkRequest,
    CachingStrategy cachingStrategy = const ExpiryCache(),
  }) async {
    Box cacheBox = await _openCache(cacheKey);
    return await cachingStrategy.get(networkRequest, cacheBox);
  }

  Stream<T> getOrUpdateStream<T extends CacheItem>({
    required String cacheKey,
    required Function networkRequest,
    CachingStrategy cachingStrategy = const ExpiryCache(),
  }) async* {
    Box cacheBox = await _openCache(cacheKey);
    await for (T result in cachingStrategy.getStream(networkRequest, cacheBox))
      yield result;
  }

  Future<Box> _openCache(String cacheKey) async {
    if (Hive.isBoxOpen(cacheKey)) {
      return Hive.box(cacheKey);
    }

    return await Hive.openBox(cacheKey);
  }

  Future dispose() async {
    var futures = <Future>[];
    for (String cacheKey in registry) {
      futures.add(Hive.box(cacheKey).close());
    }
    await Future.wait(futures);
  }
}

The cache consists of a few methods.

getOrUpdate fetches from the cache or updates it with the network result, if the data does not exist, and then returns the result.
getOrUpdateStream is the equivalent of getOrUpdate but returns a Stream in stead of a Future
dispose just closes the cache after use
clear will wipe the cache clean.

Breaking it down

I want to focus primarily on getOrUpdate as it's the most commonly used and also the most important.

Future<T> getOrUpdate<T extends CacheItem>({
  required String cacheKey,
  required Function networkRequest,
  CachingStrategy cachingStrategy = const ExpiryCache(),
}) async {
  Box cacheBox = await _openCache(cacheKey);
  return await cachingStrategy.get(networkRequest, cacheBox);
}

Type requirements

Looking at the signature of this method we can see it takes in a type T that extends CacheItem. A CacheItem is an abstract class that we use to identify objects that can be cached, it also provides a field to the concrete implementation that notifies the cache when the data was initially stored.

abstract class CacheItem {
  int cachedMilliseconds = 0;
}

Using our Countries example we can see how the CacheItem along with Hive is implemented on the object and fulfils the type requirements of our getOrUpdate method.

part 'countries.g.dart';

@JsonSerializable()
@HiveType(typeId: CacheTypeId.countries)
class Countries implements CacheItem {
  @HiveField(1)
  @JsonKey(name: 'items')
  List<Country>? countriesList;

  @JsonKey(ignore: true)
  @HiveField(2)
  @override
  int cachedMilliseconds;

  Countries({
    this.cachedMilliseconds = 0,
    countriesList,
  });

  factory Countries.fromJson(Map<String, dynamic> json) =>
      _$CountriesFromJson(json);

  Map<String, dynamic> toJson() => _$CountriesToJson(this);
}

Arguments

cacheKey is used to identify the Box in which Hive will store the data
cachingStrategy will perform the caching instructions based on its strategy type.
networkRequest will be handed to the cachingStrategy

Opening the box

Next we'll look at the body of our method.

Box cacheBox = await _openCache(cacheKey);
return await cachingStrategy.get(networkRequest, cacheBox);

Firstly the _openCache method is called, this method will use the cacheKey to identify which Box is related to our data and then check if the hive Box has been opened and ready to use, if not it will open the Box so that we can retrieve or write data into it. When the Box has been opened we send it along with the network request to the caching strategy for caching procedure.

CachingStrategy

A CachingStrategy is an abstract class that dictates what the caching strategy should look like but also provides some basic functions that each strategy would be using.

abstract class CachingStrategy<T>{
  const CachingStrategy();

  final fieldKey = 'field_type_key';
  Future<T> get<T>(Function networkRequest, Box box);
  Stream<T> getStream<T>(Function networkRequest, Box box);

  Future<void> addToCache<T>(T networkValue, Box box) async {
    if (networkValue is CacheItem) {
      networkValue.cachedMilliseconds = DateTime
          .now()
          .millisecondsSinceEpoch;
      box.put(fieldKey, networkValue);
    }
  }
}

The ExpiryCache serves as our default caching strategy, it provides functionality that allows the Repository to fetch data from the cache up to a certain point in time. If the data has expired it will be discarded and replaced with new data from the REST service. Here is the implementation for this cache.

class ExpiryCache extends CachingStrategy {
  static const _defaultDuration = const Duration(hours: 24);

  const ExpiryCache({this.duration = _defaultDuration});

  final Duration duration;

  Future<T> get<T extends CacheItem>(Function networkRequest, Box cacheBox) async {
    T? cachedValue = cacheBox.get(fieldKey);
    if (cachedValue == null || _hasCacheExpired(cachedValue)) {
      T t = await networkRequest();
      addToCache(t, cacheBox);
      return t;
    } else {
      return cachedValue;
    }
  }

  @override
  Stream<T> getStream<T extends CacheItem>(Function networkRequest, Box box) async* {
    T? cachedValue = box.get(fieldKey);
    if (cachedValue == null || _hasCacheExpired(cachedValue)) {
      T t = await networkRequest();
      addToCache(t, box);
      yield t;
    } else {
      yield cachedValue;
    }
  }

  bool _hasCacheExpired(CacheItem cachedValue) {
    int nowMilliseconds = DateTime.now().millisecondsSinceEpoch;
    int cacheExpiryMilliseconds = nowMilliseconds - duration.inMilliseconds;
    bool hasCacheExpired = cachedValue.cachedMilliseconds < cacheExpiryMilliseconds;
    return hasCacheExpired;
  }
}

In the above code we can see that there are one of two outcomes for both the get and getStream methods.

The data is available and has not expired.
In this case the data will be immediately returned to the repository for processing.
The data has either not been cached or has expired.
Here the networkRequest will be executed, if the request is successful the data will be cached and thereafter handed back to the repository for processing.

Wrap Up

To look back at what you just plowed through.

The NetworkCache is created within our Repository.
The Repository call to the http client is wrapped with the cache getOrUpdate method.
The getOrUpdate method calls the strategy that has been passed into it with the network request and Hive Box linked to the cache key.
If the strategy is our ExpiryCache it will check if there is cached data that has not expired and return it otherwise it will fetch it from the rest client and return that in stead.
The repository returns the data to its ViewModel and you have come full circle.

We have found hive reliable, stable and secure. It has worked wonderfully with our http client implementation and has delivered on the performance promises that has been made. The application has also passed quite a few penetration tests by trained professionals. Generally the disk cache of an application tends to be a weak point in a penetration test but with hive that was not the case.

Bonus Round

We have another CachingStrategy called OverridingCache! I'm not going to go into too much detail here but this strategy will essentially immediately return the data contained within the cache but at the same time query the rest client for new data and update the cache with this data immediately after it received a response. Using the Stream part of the CachingStrategy is ideal here because you can immediately return data and moments later update the view with the latest information.

This cache could theoretically work in the transactions list scenario. The last known transactions, retrieved from the cache, would be displayed with a timestamp linked to the stored data. The list will then be updated with the new data retrieved from the rest service as soon as it arrives creating a better experience for your user!

Here is the code for the OverridingCache if you're keen to see that too.

class OverridingCache extends CachingStrategy {
  @override
  Future<T> get<T extends CacheItem>(Function networkRequest, Box cacheBox) async {
    T? cachedValue = await cacheBox.get(fieldKey);
    if (cachedValue != null) {
      getAndCacheNetworkValue(networkRequest, cacheBox);
      return cachedValue;
    } else {
      return getAndCacheNetworkValue(networkRequest, cacheBox);
    }
  }

  @override
  Stream<T> getStream<T extends CacheItem>(Function networkRequest, Box box) async* {
    T? cachedValue = await box.get(fieldKey);
    if (cachedValue != null) {
      yield cachedValue;
    }

    yield await getAndCacheNetworkValue(networkRequest, box);
  }

  Future<T> getAndCacheNetworkValue<T>(Function networkRequest, Box cacheBox) async {
    T networkResult = await networkRequest();
    addToCache(networkResult, cacheBox);
    return networkResult;
  }
}

Thank you!

If you got this far, thank you for sticking it through. I hope this post was of some value to you even if it was just for some relaxation.

Please leave a comment if you have questions or suggestions on the process that we followed.

Come join our conversations on Twitter I would love to connect with you.

Attributions

All Gifs found on Giphy
Header created by Freepik

Effective handover of api responses to your code in dart

Neil — Tue, 14 Dec 2021 19:39:21 +0000

Caveat - If you're not familiar with generics some of the code in this article might be a little confusing to you. I suggest reading up more on dart generics at Dart Academy. No need to worry, I'll wait here till you are more familiar with generics and then keep on explaining when you are ready! 😁

So you're consuming an API

One of the most common requirements in mobile applications is to consume an API. From the basic to some of the more complex applications out there use this to communicate either with a 3rd party service, talk to an application server or interact with server-less infrastructure like Firebase or the like.

When building code that consumes APIs there will always be some good stuff coming back but it could also send some bad stuff your way, in this post I'll take you through how we can effectively pass different types of responses back to our code and always expect the same result.

Enough Talking, let's get into it

Generally when an API call is made there would be a few steps you would need to take before you can use the data returned from the host.

Call the endpoint
Wait for the response
Parse the data or handle any errors
Use the data in your code or show an error to the user

For most of this article I'll be using a single endpoint, extracted from one of our apps, that uses our own implementation of the dart http client for example purposes.

This endpoint will try and fetch a list of products from our API.

  Future<ProductResponse> getProducts(String country) async {
    return ProductResponse.fromJson(await _httpClient.get(
      endpoint: UrlPaths.PRODUCTS,
      endpointHeaders: {'Authorization': token},
      queryParameters: {
        r'pay_in_country': country,
      },
    ));
  }

There can be two types of responses for this endpoint

A successful response with a list of products
A error response with a code that defines what went wrong

To fetch the data we could simply call the getProducts method in our rest client and handle the response. That could look something like this.

try {
 final productResponse = await restClient.getProducts(country);
  for (var product in productResponse.items) {
    print(product.name);
  }
} on http.ClientException catch (e) {
  showErrorMessage(getErrorFromException(e));
} on TimeoutException catch (e) {
  showErrorMessage(getErrorFromException(e));
} on NetworkException catch (e) {
  // This is a specific type of exception 
  // that my client throws when there is an error code
  showErrorMessage(getErrorFromException(e));
}

This is fine, we're handling errors and using the data when we receive it successfully but you're probably asking yourself, is there a better way of doing this without all of the try catch boilerplate? 🤔

There's a better way

At Mukuru we use something called the Repository Pattern that provides our business logic with easy to use methods to fetch data from our server.

A simple diagram for illustration purposes

Although this diagram is cool it, and using the repository pattern in architectural design, is not the purpose of this article. This pattern just facilitates something that we call the NetworkResponse.

What is the `NetworkResponse`

First we have to find out how it works. We can start by calling the getProducts method again but this time the result will come from our repository in the form of NetworkResponse.

Let's get our products

NetworkResponse productsResponse = await myRepository.getProducts(myCountryCode);
if (productsResponse.isSuccessful) {
  final products = productsRepsonse.result.items;
  for (var product in products) {
    print(product.name);
  }
} else {
  showErrorMessage(productsResponse.failure);
}

You can see that the result of our getProducts call is quite different coming from the repository than it is coming from the rest client in our earlier implementation.

Let's look at what the repository does when we call getProducts to return the NetworkResponse.

  Future<NetworkResponse<ProductResponse, NetworkException>> getProducts(
      String country) async {
    return makeRequest(() => restClient.getProducts(country));
  }

Looking at the above code you might notice two things.

1. The makeRequest wrapper
The method makeRequest wrapping our getProducts call is a method defined in the base of all our repositories that handles the result from the server.

Here is a simplified implementation of what makeRequest looks like.

  Future<NetworkResponse<T, NetworkException>> makeRequest<T>(Function request) async {
    if (await hasInternetConnection()) {
      try {
        final T result = await request();
        return NetworkResponse.success(result);
      } on SocketException {
        return NetworkResponse.failure(NetworkException(Strings.couldNotReachServer));
      } on TimeoutException {
        return NetworkResponse.failure(NetworkException(Strings.couldNotReachServer));
      } on NetworkException catch (networkException) {
        return NetworkResponse.failure(getErrorFromException(networkException));
      }
    } else {
      return NetworkResponse.failure(NetworkException(Strings.noNetworkException));
    }
  }

All network calls will be executed by makeRequest by passing the unexecuted future function as an argument and executing it in the the method. The result would then either pass or fail in this function, handled, and would be returned as a NetworkResponse to the repository allowing us to always return the same object as a result.

The makeRequest method could also sit in the rest client itself but that's an architectural decision and out of the scope of this post.

2. The two generic arguments that NetworkResponse consists of

class NetworkResponse<S, F> {
  S? _s;
  F? _f;

  factory NetworkResponse.success(S _s) => NetworkResponse._(_s, null);
  factory NetworkResponse.failure(F _f) => NetworkResponse._(null, _f);

  NetworkResponse._(this._s, this._f);

  bool isSuccessful() => _f == null;

  S? result() => _s;
  F? failure() => _f;
}

Above is our NetworkResponse object, here you can see that it consists of two generic types. The first S is used as a success type and the second F as the failure type. We then have a few helper methods making it easier for the code using this object to see if the response was successful and to get the result based on that.

Wrap Up

With this new knowledge on NetworkResult and repositories let's look at this code again with some more detail.

NetworkResponse<ProductResponse, NetworkException> productsResponse = await myRepository.getProducts(myCountryCode);
if (productsResponse.isSuccessful) {
  final products = productsRepsonse.result.items;
  for (var product in products) {
    print(product.name);
  }
} else {
  showErrorMessage(productsResponse.failure);
}

We see that calling the getProducts method in our repository triggers a call to the rest client via the makeRequest method.
The rest client will call the API, parse the response and give back the data OR throw an exception on an error code or if something else goes wrong.
The makeRequest method will receive the data or the exception based on what happened in the rest client and hand back the NetworkResponse result back to the getProducts method
The NetworkResponse is then given back as a result to our code above.

The beauty of this is that you can always expect the same result from any endpoint and you will almost never need to use a try catch in your code calling APIs again.

I hope this was not a waste of your time! Be kind 👇

Header supplied by - www.freepik.com

DEV Community: Neil

Caching a NetworkResponse from the dart http client using Hive

The Repository Pattern

There was no caching to start with 😬

The NetworkCache was born

Let's dive on in

Breaking it down

Type requirements

Arguments

Opening the box

CachingStrategy

Wrap Up

Bonus Round

Thank you!

Effective handover of api responses to your code in dart

So you're consuming an API

Enough Talking, let's get into it

There's a better way

What is the NetworkResponse

Looking at the above code you might notice two things.

Wrap Up

The `NetworkCache` was born

What is the `NetworkResponse`