NEW: Learn SwiftUI with my free YouTube video series! >>

How to use @available to deprecate old APIs

Swift version: 5.0

Paul Hudson    @twostraws   

Swift availability checking is most commonly used to mark sections of code that should target specific versions of iOS or other platforms. However, it’s also useful when you make Swift APIs for others to use, because you can use it to mark certain calls as deprecated or even obsoleted as needed.

Let’s start with a simple example: if you have a function that used to parse some data, but now you want users to stop calling it. To do that, use @available with the deprecated flag, passing in the message you want to show:

@available(*, deprecated, message: "Parse your data by hand instead")
func parseData() { }

If you are renaming the API – for example the way one usage of flatMap() became compactMap() in Swift 4.1 – you can pass the new function name to the renamed flag like this:

@available(*, deprecated, renamed: "loadData")
func fetchData() { }

This will cause Xcode to generate a fix-it automatically – users can click Fix to have Xcode perform the rename for them.

Deprecated APIs generate warnings but can still be called. If you want to obsolete an API – stop it from being called entirely – you should use the obsoleted flag instead, specifying the minimum Swift version where it is no longer available:

@available(swift, obsoleted: 4.1, renamed: "attemptConnection")
func testConnection() { }

You can even combine deprecated and obsoleted together if you want:

@available(swift, deprecated: 4.0, obsoleted: 5.0, message: "This will be removed in v5.0; please migrate to a different API.")

Finally, there’s an introduced flag that lets you control when specific API was introduced, like this:

@available(swift, introduced: 4.2)
func loadUsers() { }

Using @available in this way lets your APIs behave just like Apple’s own – Xcode will draw red lines through deprecated methods, issue compile warnings and errors, and even automatically generate fix-its as needed.

LEARN SWIFTUI FOR FREE I wrote a massive, free SwiftUI tutorial collection, and also have a growing list of free SwiftUI tutorials on YouTube – get started today!

Available from iOS 8.0

Similar solutions…

About the Swift Knowledge Base

This is part of the Swift Knowledge Base, a free, searchable collection of solutions for common iOS questions.

Buy Testing Swift Buy Practical iOS 12 Buy Pro Swift Buy Swift Design Patterns Buy Swift Coding Challenges Buy Server-Side Swift (Vapor Edition) Buy Server-Side Swift (Kitura Edition) Buy Hacking with macOS Buy Advanced iOS Volume One Buy Advanced iOS Volume Two Buy Hacking with watchOS Buy Hacking with tvOS Buy Hacking with Swift Buy Dive Into SpriteKit Buy Swift in Sixty Seconds Buy Objective-C for Swift Developers Buy Beyond Code

Was this page useful? Let us know!

Average rating: 4.3/5