What is Deprecation of APIs?

If get to know something new by reading my articles, don't forget to endorse me on LinkedIn

A deprecated API is one that you are no longer recommended to use, due to changes in the API. While deprecated classes, methods, and fields are still implemented, they may be removed in future implementations, so you should not use them in new code, and if possible rewrite old code not to use them.

In sense of Java/Kotlin:

A program element annotated @Deprecated is one that programmers are discouraged from using, typically because it is dangerous, or because a better alternative exists.

Okay, let's simplify this. Think about a class, we have a or some important business logic (APIs) which are working fine & currently in production. There is nothing wrong with it, but clients want some changes or addition to the business logic. So, what do we do? Just simply working on the APIs changes? No. We should keep the current APIs as it is. [ If it's working, then don't touch it (:p) ]

Instead of changing the APIs, we work on the new APIs with client changes and simply Deprecated the old APIs and replace Deprecated APIs with new APIs. Simple, huh? Yes. Also, by keeping the Deprecated APIs for a certain version helps you to revert back to the working version if something goes wrong.... But keep in mind that Deprecation means it will be removed from the codebase (if required) in future version and no longer maintain properly.

Let's take a look at the coding part.

class SDK {
    fun doSomething(): String = "Working. Working.. Working..."
}

We have a class call SDK which contain a single API doSomething(). But client came up with some changes and we have written a new API called doSomethingNew().

class SDK {
    fun doSomething(): String = "Working. Working.. Working..."

    fun doSomethingNew(): String = "Working. Working.. Working... 24 hours working..."
}

So, we have two APIs for the same task and it's confusing. So, what to do? We can simply Deprecated the old API.

class SDK {
    @Deprecated("Use new API")
    fun doSomething(): String = "Working. Working.. Working..."

    fun doSomethingNew(): String = "Working. Working.. Working... 24 hours working..."
}

If we are using Deprecated APIs in our codebase, IDE will show the Deprecation Popup.

Let's take a look at the Deprecation annotation in Kotlin.

public annotation class Deprecated(
    val message: String,
    val replaceWith: ReplaceWith = ReplaceWith(""),
    val level: DeprecationLevel = DeprecationLevel.WARNING
)

Deprecated Annotation takes a message, replaceWith to replace the old API with new API [by using IDE (Alt+E)], level Deprecation level.

public annotation class ReplaceWith(val expression: String, vararg val imports: String)

ReplaceWith takes expression, the new API name including params, and imports to import packages if required.

public enum class DeprecationLevel {
    /** Usage of the deprecated element will be reported as a warning. */
    WARNING,
    /** Usage of the deprecated element will be reported as an error. */
    ERROR,
    /** Deprecated element will not be accessible from code. */
    HIDDEN
}

Let's update our SDK class with:

class SDK {
    @Deprecated("Use new API", ReplaceWith("doSomethingNew()"))
    fun doSomething(): String = "Working. Working.. Working..."

    fun doSomethingNew(): String = "Working. Working.. Working... 24 hours working..."
}

We have added ReplaceWith("doSomethingNew()") to identify that, to replace with which API. Our IDE will take care of that.

Just click on Replace with and IDE will replace the API.

Another fun fact.

If you press, Ctrl+Shift+Alt+T (on Windows) and enable Optimize imports and Code cleanup, IDE will automatically replace the Deprecated APIs with new defined APIs for us.

Fun right?

Happy Coding.

Follow me on LinkedIn: