Ignorance of the URLRequest cache

Caching and invalidating cache is one of the hardest things in computer science according to Martin Fowler.

Kristaps Grinbergs
Jan 19 · 4 min read
Thanks to undraw.co for a great illustration

Recently I was dealing with cache and invalidating it in three of my applications. I had some serious issues with that and wanted to dig deeper. This time we will discuss URLRequest caching strategies and how to use it in your apps. I will share some of my learnings and problems that I found.

Creating URLRequest with cache

Not so many of us use a caching strategy when creating URLRequest and hitting the network. If the server you’re accessing doesn’t have caching strategy implemented then making network requests can cause data corruption in your apps.

I had these issues with just a simple request and getting new JSON data from the network. For some reason, URLRequest thought that nothing has changed and returned data from the internal app cache rather than the network.

The reason for this is that NSURLCache is set for the application by default according to the documentation. The cache will be purged when the device runs low on disk space, but mostly this isn’t the case. You can control NSURLCache behavior when launching the app but let’s leave that for another post.

Caching strategies

NSURLRequest has a property cachePolicy which sets the caching strategy for the request you’re creating. It is an enum and has several choices defined as constants:

  • case useProtocolCachePolicy
  • case reloadIgnoringLocalCacheData
  • case reloadIgnoringLocalAndRemoteCacheData
  • static var reloadIgnoringCacheData: NSURLRequest.CachePolicy
  • case returnCacheDataElseLoad
  • case returnCacheDataDontLoad
  • case reloadRevalidatingCacheData

If you just read the documentation then all of these constants look confusing and hard to choose the right now. Let’s try to understand which of the caching policy you need to choose for your URLRequest and when.

Which one to choose?

The default policy for URL load requests is useProtocolCachePolicy. If a cached response does not exist then it is fetched from the originating source. Otherwise, if a response doesn’t tell to revalidate then a response is returned from the cache. For more detailed information you can go to RFC 2616 detailed documentation. Here is an image to illustrate how this policy works.

Option reloadIgnoringLocalCacheData ignores the local cache and reloadIgnoringLocalAndRemoteCacheData ignores local and remote cache.

With returnCacheDataElseLoad you tell to use cache no matter how out of date it is. If the cached request doesn’t exist it will be loaded from the network.

Option returnCacheDataDontLoad is the most confusing one. It means offline mode. Only cached data will be used and it won’t load from the network.

But the story doesn’t end here, if we check reloadRevalidatingCacheData documentation then we see that previous versions than macOS 15, iOS 13, watchOS 6, and tvOS 13 don’t implement this constant. Mattt was warning us about that years ago. There is a radar opened in May 2012.

So which one to choose? There isn’t a right or wrong answer, but the rule of thumb is — if you want partial cache with default settings then choose useProtocolCachePolicy. If you want to load a request without cache then choose either reloadIgnoringLocalCacheData or reloadIgnoringLocalAndRemoteCacheData.


Handling cache and cache invalidation are one of the hardest topics in Computer Science. In iOS, macOS, tvOS and watchOS it isn’t easy and straight forward. The official documentation is confusing and isn’t clear how it works behind the scenes.

URLRequest has a property cachePolicy that sets the caching strategy for the request.

For most of the cases default useProtocolCachePolicy option is what you want. If you want to avoid cache then one of reloadIgnoringLocalCacheData or reloadIgnoringLocalAndRemoteCacheData is the right one you have to choose.


Flawless iOS

🍏 Community around iOS development, mobile design, and marketing

Kristaps Grinbergs

Written by

Co-founder and Swift (iOS, tvOS) developer at @Qminder. Love cycling and cats. I care about inclusivity.

Flawless iOS

🍏 Community around iOS development, mobile design, and marketing

More From Medium

More from Flawless iOS

More from Flawless iOS

More from Flawless iOS

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade