Kotlin is known for its concise, expressive syntax and developer-friendly features. However, if you’ve worked with certain Kotlin libraries, you may have encountered a Delicate API warning. This warning often leaves developers wondering: Should I ignore it? or Is it something I need to worry about?

Let’s break it down in simple terms so you can make an informed decision.

What is a Delicate API in Kotlin?

A Delicate API in Kotlin is an API that requires extra caution. It’s not necessarily unsafe, but misusing it can lead to unexpected behavior, bugs, or maintenance headaches.

When you use a Delicate API, the compiler warns you with a message like this:

fun riskyFunction() {
    GlobalScope.launch { // warning: Launching coroutine in an unsafe way
        println("Running in GlobalScope")
    }
}

In this snippet, launching a coroutine in the GlobalScope triggers the delicate API warning, reminding you to handle this coroutine with care. Actually, it creates a coroutine that lives for the application’s lifetime, which can lead to memory leaks if not handled correctly.

Why Does Kotlin Mark APIs as Delicate?

Kotlin marks certain APIs as Delicate for the following reasons:

1. Potential for Misuse — Some APIs can cause memory leaks, thread issues, or unexpected behavior if used incorrectly.
2. Encouraging Safer Alternatives — Kotlin wants developers to use best practices, and marking APIs as Delicate nudges them toward better alternatives.
3. API Evolution — Some APIs might change or be deprecated in the future, and this warning helps developers prepare for that.

Should You Ignore the Delicate API Warning?

Ignoring a Delicate API warning isn’t always a bad idea, but it depends on the situation. Let’s look at both sides:

When It’s Safe to Use

• You Fully Understand the API — If you know the risks and how to mitigate them, you can use the API confidently.
• It’s Necessary for Your Use Case — Some APIs are marked delicate but still provide valuable functionality in specific scenarios.
• You Have Proper Handling — If you ensure proper cleanup and error handling, using a Delicate API can be justified.

For example, if you’re working on a quick prototype and don’t mind the risks, using GlobalScope.launch might be acceptable. But in a production environment, you’d typically use structured concurrency instead, like viewModelScope or lifecycleScope.

When You Should Avoid

• You’re Uncertain About Its Behavior — If you’re not sure why an API is delicate, it’s best to look for alternatives.
• There’s a Recommended Alternative — Many delicate APIs have safer, preferred alternatives that avoid potential pitfalls.
• Long-Term Maintenance Matters — If your codebase is meant to be maintained by a team, using a Delicate API might create future headaches.

How to Properly Use a Delicate API

If you decide to use a Delicate API, Kotlin requires you to explicitly opt-in by adding the @OptIn annotation. Here’s how:

@OptIn(DelicateCoroutinesApi::class)
fun safeUsage() {
    GlobalScope.launch {
        println("Running in a GlobalScope coroutine")
    }
}

Alternatively, if you’re working in a file where you need multiple delicate APIs, you can opt in at the file level:

@file:OptIn(DelicateCoroutinesApi::class)

fun anotherFunction() {
    GlobalScope.launch {
        println("Using a Delicate API")
    }
}

This tells Kotlin that you acknowledge the risks and accept responsibility for using the API correctly.

Best Practices for Avoiding Issues

If you want to write safe and maintainable Kotlin code, follow these best practices:

1. Prefer Structured Concurrency — Instead of GlobalScope.launch, use CoroutineScope and viewModelScope in Android apps.
2. Read the Documentation — Understand why an API is marked delicate before using it.
3. Look for Alternatives — Kotlin often provides safer ways to achieve the same goal.
4. Use @OptIn Wisely – Only opt-in when you are confident in the API’s behavior.
5. Keep Code Maintainable — If others will work on your code, document why you chose to use this API.

Conclusion

Kotlin’s Delicate API warning isn’t there to annoy you — it’s a helpful reminder to be cautious. While you can ignore it by opting in, it’s best to understand why an API is marked delicate before doing so. If there’s a safer alternative, use it. If you must use a Delicate API, do so responsibly and document your reasoning.