NEW! Master Swift design patterns with my latest book! >>

How to use @available to deprecate old APIs

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.

Available from iOS 8.0

Did this solution work for you? Please pass it on!

Other people are reading…

About the Swift Knowledge Base

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

Get the ultimate experience

The Swift Power Pack includes my first six books for one low price, helping you jumpstart a new career in iOS development – check it out!

MASTER SWIFT NOW
Buy Practical iOS 12 Buy Pro Swift Buy Swift Design Patterns Buy Practical iOS 11 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 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 me know!

Click here to visit the Hacking with Swift store >>