| September 14, 2021
No comments

Build Offline-First Mobile Apps by Caching API Results in Realm

Note that this post was originally published at Build Offline-First Mobile Apps by Caching API Results in Realm.

Introduction

When building a mobile app, there’s a good chance that you want it to pull in data from a cloud service—whether from your own or from a third party. While other technologies are growing (e.g., GraphQL and MongoDB Realm Sync), REST APIs are still prevalent.

It’s easy to make a call to a REST API endpoint from your mobile app, but what happens when you lose network connectivity? What if you want to slice and dice that data after you’ve received it? How many times will your app have to fetch the same data (consuming data bandwidth and battery capacity each time)? How will your users react to a sluggish app that’s forever fetching data over the internet?

By caching the data from API calls in Realm, the data is always available to your app. This leads to higher availability, faster response times, and reduced network and battery consumption.

This article shows how the RCurrency mobile app fetches exchange rate data from a public API, and then caches it in Realm for always-on, local access.

Is Using the API from Your Mobile App the Best Approach?

This app only reads data through the API. Writing an offline-first app that needs to reliably update cloud data via an API is a far more complex affair. If you need to update cloud data when offline, then I’d strongly recommend you consider MongoDB Realm Sync.

Many APIs throttle your request rate or charge per request. That can lead to issues as your user base grows. A more scalable approach is to have your backend Realm app fetch the data from the API and store it in Atlas. Realm Sync then makes that data available locally on every user’s mobile device—without the need for any additional API calls.

Prerequisites

The RCurrency Mobile App

The RCurrency app is a simple exchange rate app. It’s intended for uses such as converting currencies when traveling.

You choose a base currency and a list of other currencies you want to convert between.

When opened for the first time, RCurrency uses a REST API to retrieve exchange rates, and stores the data in Realm. From that point on, the app uses the data that’s stored in Realm. Even if you force-close the app and reopen it, it uses the local data.

If the stored rates are older than today, the app will fetch the latest rates from the API and replace the Realm data.

The app supports pull-to-refresh to fetch and store the latest exchange rates from the API.

You can alter the amount of any currency, and the amounts for all other currencies are instantly recalculated.

Animation of the RCurrency app running on an iPhone. Includes the user selecting currencies, changing amounts and observing the amounts changing for other currencies

The REST API

I’m using the API provided by exchangerate.host. The API is a free service that provides a simple API to fetch currency exchange rates.

One of the reasons I picked this API is that it doesn’t require you to register and then manage access keys/tokens. It’s not rocket science to handle that complexity, but I wanted this app to focus on when to fetch data, and what to do once you receive it.

The app uses a single endpoint (where you can replace USD and EUR with the currencies you want to convert between):

https://api.exchangerate.host/convert?from=USD&to=EUR

You can try calling that endpoint directly from your browser.

The endpoint responds with a JSON document:

{
  "motd": {
    "msg": "If you or your company use this project or like what we doing, please consider backing us so we can continue maintaining and evolving this project.",
    "url": "https://exchangerate.host/#/donate"
  },
  "success": true,
  "query": {
    "from": "USD",
    "to": "EUR",
    "amount": 1
  },
  "info": {
    "rate": 0.844542
  },
  "historical": false,
  "date": "2021-09-02",
  "result": 0.844542
}

Note that the exchange rate for each currency is only updated once every 24 hours. That’s fine for our app that’s helping you decide whether you can afford that baseball cap when you’re on vacation. If you’re a currency day-trader, then you should look elsewhere.

The RCurrency App Implementation

Data Model

JSON is the language of APIs. That’s great news as most modern programming languages (including Swift) make it super easy to convert between JSON strings and native objects.

The app stores the results from the API query in objects of type Rate. To make it as simple as possible to receive and store the results, I made the Rate class match the JSON format of the API results:

class Rate: Object, ObjectKeyIdentifiable, Codable {
    var motd = Motd()
    var success = false
    @Persisted var query: Query?
    var info = Info()
    @Persisted var date: String
    @Persisted var result: Double
}

class Motd: Codable {
    var msg = ""
    var url = ""
}

class Query: EmbeddedObject, ObjectKeyIdentifiable, Codable {
    @Persisted var from: String
    @Persisted var to: String
    var amount = 0
}

class Info: Codable {
    var rate = 0.0
}

Note that only the fields annotated with @Persisted will be stored in Realm.

Swift can automatically convert between Rate objects and the JSON strings returned by the API because we make the class comply with the Codable protocol.

There are two other top-level classes used by the app.

Symbols stores all of the supported currency symbols. In the app, the list is bootstrapped from a fixed list. For future-proofing, it would be better to fetch them from an API:

class Symbols {
    var symbols = Dictionary<String, String>()
}

extension Symbols {
    static var data = Symbols()


    static func loadData() {
        data.symbols["AED"] = "United Arab Emirates Dirham"
        data.symbols["AFN"] = "Afghan Afghani"
        data.symbols["ALL"] = "Albanian Lek"
        ...
    }
}

UserSymbols is used to store the user’s chosen base currency and the list of currencies they’d like to see exchange rates for:

class UserSymbols: Object, ObjectKeyIdentifiable {
    @Persisted var baseSymbol: String
    @Persisted var symbols: List<String>
}

An instance of UserSymbols is stored in Realm so that the user gets the same list whenever they open the app.

Rate Data Lifecycle

This flowchart shows how the exchange rate for a single currency (represented by the symbol string) is managed when the CurrencyRowContainerView is used to render data for that currency:

Flowchart showing how the app fetches data from the API and stored in in Realm. The mobile app's UI always renders what's stored in MongoDB. The following sections will describe each block in the flow diagram.

Note that the actual behavior is a little more subtle than the diagram suggests. SwiftUI ties the Realm data to the UI. If stage #2 finds the data in Realm, then it will immediately get displayed in the view (stage #8). The code will then make the extra checks and refresh the Realm data if needed. If and when the Realm data is updated, SwiftUI will automatically refresh the UI to render it.

Let’s look at each of those steps in turn.

#1 CurrencyContainerView loaded for currency represented by symbol

CurrencyListContainerView iterates over each of the currencies that the user has selected. For each currency, it creates a CurrencyRowContainerView and passes in strings representing the base currency (baseSymbol) and the currency we want an exchange rate for (symbol):

List {
   ForEach(userSymbols.symbols, id: \.self) { symbol in
       CurrencyRowContainerView(baseSymbol: userSymbols.baseSymbol,
                                   baseAmount: $baseAmount,
                                   symbol: symbol,
                                   refreshNeeded: refreshNeeded)
   }
   .onDelete(perform: deleteSymbol)
}

#2 rate = FetchFromRealm(symbol)

CurrencyRowContainerView then uses the @ObservedResults property wrapper to query all Rate objects that are already stored in Realm:

struct CurrencyRowContainerView: View {
   @ObservedResults(Rate.self) var rates
   ...
}

The view then filters those results to find one for the requested baseSymbol/symbol pair:

var rate: Rate? {
   rates.filter(
       NSPredicate(format: "query.from = %@ AND query.to = %@",
                   baseSymbol, symbol)).first
}

#3 rate found?

The view checks whether rate is set or not (i.e., whether a matching object was found in Realm). If rate is set, then it’s passed to CurrencyRowDataView to render the details (step #8). If rate is nil, then a placeholder “Loading Data…” TextView is rendered, and loadData is called to fetch the data using the API (step #4-3):

var body: some View {
   if let rate = rate {
       HStack {
           CurrencyRowDataView(rate: rate, baseAmount: $baseAmount, action: action)
           ...
       }
   } else {
       Text("Loading Data...")
           .onAppear(perform: loadData)
   }
}

#4-3 Fetch rate from API — No matching object found in Realm

The API URL is formed by inserting the base currency (baseSymbol) and the target currency (symbol) into a template string. loadData then sends the request to the API endpoint and handles the response:

private func loadData() {
   guard let url = URL(string: "https://api.exchangerate.host/convert?from=\(baseSymbol)&to=\(symbol)") else {
       print("Invalid URL")
       return
   }
   let request = URLRequest(url: url)
   print("Network request: \(url.description)")
   URLSession.shared.dataTask(with: request) { data, response, error in
       guard let data = data else {
           print("Error fetching data: \(error?.localizedDescription ?? "Unknown error")")
           return
       }
       if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
           // TODO: Step #5-3
       } else {
           print("No data received")
       }
   }
   .resume()
}

#5-3 StoreInRealm(rate) — No matching object found in Realm

Rate objects stored in Realm are displayed in our SwiftUI views. Any data changes that impact the UI must be done on the main thread. When the API endpoint sends back results, our code receives them in a callback thread, and so we must use DispatchQueue to run our closure in the main thread so that we can add the resulting Rate object to Realm:

if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
   DispatchQueue.main.async {
       $rates.append(decodedResponse)
   }
} else {
   print("No data received")
}

Notice how simple it is to convert the JSON response into a Realm Rate object and store it in our local realm!

#6 Refresh Requested?

RCurrency includes a pull-to-refresh feature which will fetch fresh exchange rate data for each of the user’s currency symbols. We add the refresh functionality by appending the .refreshable modifier to the List of rates in CurrencyListContainerView:

List {
   ...
}
.refreshable(action: refreshAll)

refreshAll sets the refreshNeeded variable to true, waits a second to allow SwiftUI to react to the change, and then sets it back to false:

private func refreshAll() {
   refreshNeeded = true
   DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
       refreshNeeded = false
   }
}

refreshNeeded is passed to each instance of CurrencyRowContainerView:

CurrencyRowContainerView(baseSymbol: userSymbols.baseSymbol,
                        baseAmount: $baseAmount,
                        symbol: symbol,
                        refreshNeeded: refreshNeeded)

CurrencyRowContainerView checks refreshNeeded. If true, it displays a temporary refresh image and invokes refreshData (step #4-6):

if refreshNeeded {
   Image(systemName: "arrow.clockwise.icloud")
       .onAppear(perform: refreshData)
}

#4-6 Fetch rate from API — Refresh requested

refreshData fetches the data in exactly the same way as loadData in step #4-3:

private func refreshData() {
   guard let url = URL(string: "https://api.exchangerate.host/convert?from=\(baseSymbol)&to=\(symbol)") else {
       print("Invalid URL")
       return
   }
   let request = URLRequest(url: url)
   print("Network request: \(url.description)")
   URLSession.shared.dataTask(with: request) { data, response, error in
       guard let data = data else {
           print("Error fetching data: \(error?.localizedDescription ?? "Unknown error")")
           return
       }
       if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
           DispatchQueue.main.async {
               // TODO: #5-5
           }
       } else {
           print("No data received")
       }
   }
   .resume()
}

The difference is that in this case, there may already be a Rate object in Realm for this currency pair, and so the results are handled differently…

#5-6 StoreInRealm(rate) — Refresh requested

If the Rate object for this currency pair had been found in Realm, then we reference it with existingRate. existingRate is then updated with the API results:

if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
   DispatchQueue.main.async {
       if let existingRate = rate {
           do {
               let realm = try Realm()
               try realm.write() {
                   guard let thawedrate = existingRate.thaw() else {
                       print("Couldn't thaw existingRate")
                       return
                   }
                   thawedrate.date = decodedResponse.date
                   thawedrate.result = decodedResponse.result
               }
           } catch {
               print("Unable to update existing rate in Realm")
           }
       }
   }
}

#7 rate stale?

The exchange rates available through the API are updated daily. The date that the rate applies to is included in the API response, and it’s stored in the Realm Rate object. When displaying the exchange rate data, CurrencyRowDataView invokes loadData:

var body: some View {
   CurrencyRowView(value: (rate.result) * baseAmount,
                   symbol: rate.query?.to ?? "",
                   baseValue: $baseAmount,
                   action: action)
       .onAppear(perform: loadData)
}

loadData checks that the existing Realm Rate object applies to today. If not, then it will refresh the data (stage 4-7):

private func loadData() {
   if !rate.isToday {
       // TODO: 4-7
   }
}

isToday is a Rate method to check whether the stored data matches the current date:

extension Rate {
   var isToday: Bool {
       let today = Date().description.prefix(10)
       return  date == today
   }
}

#4-7 Fetch rate from API — rate stale

By now, the code to fetch the data from the API should be familiar:

private func loadData() {
   if !rate.isToday {
       guard let query = rate.query else {
           print("Query data is missing")
           return
       }
       guard let url = URL(string: "https://api.exchangerate.host/convert?from=\(query.from)&to=\(query.to)") else {
           print("Invalid URL")
           return
       }
       let request = URLRequest(url: url)
       URLSession.shared.dataTask(with: request) { data, response, error in
           guard let data = data else {
               print("Error fetching data: \(error?.localizedDescription ?? "Unknown error")")
               return
           }
           if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
               DispatchQueue.main.async {
                   // TODO: #5.7
               }
           } else {
               print("No data received")
           }
       }
       .resume()
   }
}

#5-7 StoreInRealm(rate) — rate stale

loadData copies the new date and exchange rate (result) to the stored Realm Rate object:

if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
   DispatchQueue.main.async {
       $rate.date.wrappedValue = decodedResponse.date
       $rate.result.wrappedValue = decodedResponse.result
   }
}

#8 View rendered with rate

CurrencyRowView receives the raw exchange rate data, and the amount to convert. It’s responsible for calculating and rendering the results:

Screen capture showing the row for a single currency. In this case it shows the US flag, the "USD" symbol and the amount (3.23...)

The number shown in this view is part of a TextField, which the user can overwrite:

@Binding var baseValue: Double
...
TextField("Amount", text: $amount)
   .keyboardType(.decimalPad)
   .onChange(of: amount, perform: updateValue)
   .font(.largeTitle)

When the user overwrites the number, the onChange function is called which recalculates baseValue (the value of the base currency that the user wants to convert):

private func updateValue(newAmount: String) {
   guard let newValue = Double(newAmount) else {
       print("\(newAmount) cannot be converted to a Double")
       return
   }
   baseValue = newValue / rate
}

As baseValue was passed in as a binding, the new value percolates up the view hierarchy, and all of the currency values are updated. As the exchange rates are held in Realm, all of the currency values are recalculated without needing to use the API:

Animation showing the app running on an iPhone. When the user changes the amount for 1 currency, the amounts for all of the others changes immediately

Conclusion

REST APIs let your mobile apps act on a vast variety of cloud data. The downside is that APIs can’t help you when you don’t have access to the internet. They can also make your app seem sluggish, and your users may get frustrated when they have to wait for data to be downloaded.

A common solution is to use Realm to cache data from the API so that it’s always available and can be accessed locally in an instant.

This article has shown you a typical data lifecycle that you can reuse in your own apps. You’ve also seen how easy it is to store the JSON results from an API call in your Realm database:

if let decodedResponse = try? JSONDecoder().decode(Rate.self, from: data) {
   DispatchQueue.main.async {
       $rates.append(decodedResponse)
   }
}

We’ve focussed on using a read-only API. Things get complicated very quickly when your app starts modifying data through the API. What should your app do when your device is offline?

  • Don’t allow users to do anything that requires an update?
  • Allow local updates and maintain a list of changes that you iterate through when back online?
    • Will some changes you accept from the user have to be backed out once back online and you discover conflicting changes from other users?

If you need to modify data that’s accessed by other users or devices, consider MongoDB Realm Sync as an alternative to accessing APIs directly from your app. It will save you thousands of lines of tricky code!

The API you’re using may throttle access or charge per request. You can create a backend MongoDB Realm app to fetch the data from the API just once, and then use Realm Sync to handle the fan-out to all instances of your mobile app.

If you have any questions or comments on this post (or anything else Realm-related), then please raise them on our community forum. To keep up with the latest Realm news, follow @realm on Twitter and join the Realm global community.





Category: Realm | Tags: , ,

Leave a Reply