How to use @available to deprecate old APIs

Swift version: 5.6

Paul Hudson @twostraws May 28th 2019

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.