How to mark rpc as deprecated

Question

If I have a service like this:

service MyService {
  rpc GetThings(GetThingsRequest) returns (GetThingsResponse);
}

How would I mark GetThings as deprecated?

I know how to mark fields or messages as deprecated but I can't find any information about rpcs.

This is for proto3.

Answer 1

TL;DR: It's possible, but it does not generate a compiler warning. Consider to use field-level deprecation.

It looks like it's possible to add a deprecated option to a service, just like on a message and enum like:

service MyService {
  rpc GetThings(GetThingsRequest) returns (GetThingsResponse) {
    option deprecated = true;
  };
}

Found this in: https://github.com/google/protobuf/issues/1734

Even though it does compile, it does not seem to generate a compiler warning when used. I tried in Java, with the HelloWorld service from the Java quick start guide. Inspecting the generated java file further, HelloWorldProto.java, it shows that the class has not added a @Deprecated java annotation, but there are some differences in the file, most likely the proto annotation in the proto description:

$ diff HelloWorldProto-{control,method}.java
38c38
<       "ssage\030\001 \001(\t2I\n\007Greeter\022>\n\010SayHello\022\030.hel" +
---
>       "ssage\030\001 \001(\t2L\n\007Greeter\022A\n\010SayHello\022\030.hel" +
40,41c40,41
<       "eply\"\000B6\n\033io.grpc.examples.helloworldB\017H" +
<       "elloWorldProtoP\001\242\002\003HLWb\006proto3"
---
>       "eply\"\003\210\002\001B6\n\033io.grpc.examples.helloworld" +
>       "B\017HelloWorldProtoP\001\242\002\003HLWb\006proto3"

I got similar result when trying the option on request message, service and file level as well. My hunch is that this is a missing feature in the java code generator. When adding the deprecated option to a field, I did however get the wanted compiler warning:

$ ./gradlew installDist
...
Note: Some input files use or override a deprecated API.
...

Your options as I see it:

• Mark all fields in the request message as deprecated. Then you are going to show compiler warnings as soon as anybody uses it. Like:

  message HelloRequest {
    string name = 1 [deprecated=true];
  }
  

• Use option deprecated on the grpc method (as shown above) No compiler warnings are shown, and rely on users to just see this documentation.

• Open a github issue.
• All of the above :)