RequiresApi vs TargetApi android annotations

Question

Whats the difference between RequiresApi and TargetApi?

Sample in kotlin:

@RequiresApi(api = Build.VERSION_CODES.M)
@TargetApi(Build.VERSION_CODES.M)
class FingerprintHandlerM() : FingerprintManager.AuthenticationCallback()

NOTE: FingerprintManager.AuthenticationCallback requires api M

NOTE 2: if I dont use TargetApi lint fail with error class requires api level 23...

Answer 1

@RequiresApi - Denotes that the annotated element should only be called on the given API level or higher.

@TargetApi - Indicates that Lint should treat this type as targeting a given API level, no matter what the project target is.

Answer 2

Similar to what Mike said, as you can see in the documentation:

Denotes that the annotated element should only be called on the given API level or higher.

This is similar in purpose to the older @TargetApi annotation, but more clearly expresses that this is a requirement on the caller, rather than being used to "suppress" warnings within the method that exceed the minSdkVersion.

As you can see here, this is actually enforcing the caller to verify the API that's been used when calling into this method, instead of just removing the warning from your IDE/LINT.

You can compare this to the @NonNull or @Null annotations, they enforce that the caller can/can't send null values into the function.

Answer 3

I'll first assume your min api version is lower than the api you are going to call, because that's where these kind of annotations make any sense

@RequiresApi(Build.VERSION_CODES.N_MR1)
public void hello() { // codes that call system apis introduced in android N_MR1}

When a method is annotated with this, anytime you call that method, your receive a nice red warning that this call requires api version that is higher than your min api version, but it doesn't stop you from compiling and building your apk, it will just crash on lower versions of android as I tested it.

@TargetApi

This doesn't help at all, it suppress warnings of calling new apis in your method, but when you call this method from somewhere else, there is no lint warning at all, and you can still build and install your apk only to meet a crash when that method is called.

Answer 4

From the JavaDocs in https://developer.android.com/reference/android/support/annotation/RequiresApi.html:

[@RequiresApi] This is similar in purpose to the older @TargetApi annotation, but more clearly expresses that this is a requirement on the caller, rather than being used to "suppress" warnings within the method that exceed the minSdkVersion.

I suppose they're functionally equivalent but @RequiresApi seems to be newer and has a higher chance of being extended to include more functionality.

Answer 5

Both of them are for handling feature added to new android API levels without affecting the other API levels.

RequiresApi

@RequiresApi(api = Build.VERSION_CODES.*api_code*)

Here it says that the annotated element should only be called on the given API level or higher. The annotated element below the given API level won't call.

TargetApi

@TargetApi(Build.VERSION_CODES.*api_code*)

Indicates that Lint should treat this type as targeting a given API level, no matter what the project target is. Only meant for specified API level. Won't called on other API level.