28. Caching

Written by Tanner Nelson

Whether you’re creating a JSON API, building an iOS app or even designing the circuitry of a CPU, you’ll eventually need a cache. Caches — pronounced cashes — are a method of speeding up slow processes and, without them, the Internet would be a terribly slow place. The philosophy behind caching is simple: Store the result of a slow process so you only have to run it once. Some examples of slow processes you may encounter while building a web app are:

• Large database queries
• Requests to external services, e.g., other APIs
• Complex computation, e.g., parsing a large document

By caching the results of these slow processes, you can make your app feel snappier and more responsive.

Cache storage

Vapor defines the protocol Cache. This protocol creates a common interface for different cache storage methods. The protocol itself is quite simple; take a look:

public protocol Cache {
  // 1
  func get<T>(_ key: String, as type: T.Type) -> EventLoopFuture<T?>
    where T: Decodable
  
  // 2
  func set<T>(_ key: String, to value: T?) -> EventLoopFuture<Void>
    where T: Encodable
}

Here’s what each method does:

1. get(_:as:) fetches stored data from the cache for a given key. If no data exists for that key, it returns nil.
2. set(_:to:) stores data in the cache at the supplied key. If a value existed previously, it’s replaced. If nil, the key is cleared.

Each method returns a future since interaction with the cache may happen asynchronously.

Now that you understand the concept of caching and the Cache protocol, it’s time to take a look at some of the actual caching implementations available with Vapor.

In-memory caches

Vapor comes with an in-memory cache: .memory. This cache stores its data in your program’s running memory. This makes it great for development and testing because it has no external dependencies. However, it may not be perfect for all uses as the storage is cleared when the application restarts and can’t be shared between multiple instances of your application. Most likely though, this memory volatility won’t affect a well thought out caching design.

Thread-safety

The contents of the in-memory cache are shared across all your application’s event loops. This means once something is stored in the cache, all future requests will see that same item regardless of which event loop they are assigned to. To achieve this cross-loop sharing, the in-memory cache uses an application-wide lock to synchronize access.

Database caches

Vapor’s cache protocol supports using a configured database as your cache storage. This includes all of Vapor’s Fluent mappings (PostgreSQL, MySQL, SQLite, MongoDB, etc.).

If you want your cached data to persist between restarts and be shareable between multiple instances of your application, storing it in a database is a great choice. If you already have a database configured for your application, it’s easy to set up.

You can use your application’s main database for caching or you can use a separate, specialized database.

Redis

Redis is an open-source, cache storage service. It’s used commonly as a cache database for web applications and is supported by most deployment services like Heroku. Redis databases are usually very easy to configure and they allow you to persist your cached data between application restarts and share the cache between multiple instances of your application. Redis is a great, fast and feature-rich alternative to in-memory caches and it only takes a little bit more work to configure.

Now that you know about the available caching implementations in Vapor, it’s time to add caching to an application.

Example: Pokédex

When building a web app, making requests to other APIs can introduce delays. If the API you’re communicating with is slow, it can make your API feel slow. Additionally, external APIs may enforce rate limits on the number of requests you can make to them in a given time period.

Fortunately, with caching, you can store the results of these external API queries locally and make your API feel much faster.

You’re going to use a cache to improve the performance of Pokédex, an API for storing and listing all Pokémon you’ve captured.

You’ve already learned how to create a basic CRUD API and how to make external HTTP requests. As a result, this chapter’s starter project already has the basics implemented.

In Terminal, change to the starter project’s directory and use the following command to generate and open an Xcode project to work in:

open Package.swift

Overview

This simple Pokédex API has two routes:

• GET /pokemon: Returns a list of all captured Pokémon.
• POST /pokemon: Stores a captured Pokémon in the Pokédex.

When you store a new Pokémon, the Pokédex API makes a call to the external API pokeapi.co to verify that the Pokémon name you’ve entered is real. While this check works, the pokeapi.co API can be pretty slow to respond, thereby making your app feel slow.

Normal request

A typical Vapor requests takes only a couple of milliseconds to respond, when working locally. In the screenshot that follows, you can see the GET /pokemon route has a total response time of about 40ms.

PokeAPI dependent request

In the screenshot below, you can see that the POST /pokemon route is 25 times slower at around 1,500ms. This is because the pokeapi.co API can be slow to respond to the query.

Now you’re ready to take a look at the code to better understand what’s making this route slow and how a cache can fix it.

Verifying the name

In Xcode, open PokeAPI.swift and look at verify(name:).

This class is a simple wrapper around an HTTP client and makes querying the PokeAPI more convenient. It verifies the legitimacy of a supplied Pokémon name using verify(name:). If the name is real, the method returns true, wrapped in a future.

Now look at fetchPokemon(named:). This method sends the request to the external pokeapi.co and returns the Pokémon’s data. If a Pokémon with the supplied name doesn’t exist, the API — and, therefore, this method — returns a 404 Not Found response.

fetchPokemon(named:) is the cause of the slow response time on the POST /pokemon route. A cache is just what the doctor ordered!

Creating a cache

The first task is to create a cache for the PokeAPI wrapper. In PokeAPI.swift, add a new property to store the cache below let client: Client:

/// Cache to check before calling API.
let cache: Cache

Next, replace the implementation of init to account for the new property:

public init(client: Client, cache: Cache) {
  self.client = client
  self.cache = cache
}

Finally, fix the remaining compiler error by replacing the Request extension at the top of the file with:

extension Request {
  public var pokeAPI: PokeAPI {
    .init(client: self.client, cache: self.cache)
  }
}

By default, Vapor is configured to use the built-in memory cache.

Fetch and Store

Now that the PokeAPI wrapper has access to a working Cache, you can use the cache to store responses from the pokeapi.co API and subsequently fetch them much more quickly.

Open PokeAPI.swift and rename verify(name:) to uncachedVerify(name:). Next, add the following method to replace the uncached implementation:

public func verify(name: String) -> EventLoopFuture<Bool> {
  // 1
  let name = name
    .lowercased()
    .trimmingCharacters(in: .whitespacesAndNewlines)
  
  // 2
  return cache.get(name, as: Bool.self).flatMap { verified in
    // 3
    if let verified = verified {
      return self.client.eventLoop.makeSucceededFuture(verified)
    } else {
      return self.uncachedVerify(name: name).flatMap {
        verified in
        // 4
        return self.cache.set(name, to: verified)
          .transform(to: verified)
      }
    }
  }
}

Here’s what this does:

1. Create a consistent cache key by lowercasing the name. This ensures that both “Pikachu” and “pikachu” share the same cache result.
2. Query the cache to see if it contains the desired result.
3. If a cached result exists, return that result. This means that calls to verify(name:) will never invoke fetchPokemon(named:) a second time for a given name. This is the key step that will improve performance.
4. When fetchPokemon(named:) completes, store the result of the API query in the cache.

Build and run, then create a new request in RESTed. Configure the request as follows:

• URL: http://localhost:8080/pokemon
• method: POST
• Parameter encoding: JSON-encoded

Add one parameter with name and value:

• name: Test

Take note of the response time for the first request. It’ll likely be a couple of seconds. Now, make a second request and note the time; it should be much faster!

Fluent

Once you have configured your app to use Vapor’s cache interface, it’s easy to swap out the underlying implementation. Since this app already uses SQLite to store caught Pokémon, you can easily enable Fluent as a cache. Unlike in-memory caching, Fluent caches are shared between multiple instances of your application and are persisted between restarts.

To switch Vapor’s cache implementation to use Fluent, open configure.swift and add the following:

app.caches.use(.fluent)

just above the line:

try routes(app)

Finally, since Fluent is currently configured to use a SQL database (SQLite), it needs to be prepared to store cache values. Still inside configure.swift, find:

app.migrations.add(CreatePokemon())

and add the following migration just below it:

app.migrations.add(CacheEntry.migration)

You should now notice that cached values are persisted between application restarts. Nice!

Where to go from here?

Caching is an important concept in Computer Science and understanding how to use it will help make your web applications feel fast and responsive. There are several methods for storing your cache data for web applications: in-memory, Fluent database, Redis and more. Each has distinct benefits over the other.

You can check out the different types of algorithms available for caching such as Least Recently Used (LRU), Random Replacement (RR) or Last In First Out (LIFO). Each of these has pros and cons depending on the type of application you’re writing and the type of data you’re caching within it.

In this chapter, you learned how to configure a Fluent database cache. Using the cache to save the results of a request to an external API, you significantly increased the responsiveness of your app.

If you’d like a challenge, try configuring your app to use a Redis cache. But remember, you gotta cache ’em all!