AIP-4232

Method signatures

In protocol buffer RPCs, each RPC takes exactly one argument: a message. However, sending a full message structure can be cumbersome in the case of extremely simple requests.

Many RPCs provide information about which pieces of the request are important and commonly used. In many languages, functions and methods take multiple positional or keyword arguments.

Guidance

Some APIs provide annotations to hint how to effectively translate from a single request object to individual arguments, and client libraries may provide overloads based on these hints.

However, client libraries implementing this feature must retain the default behavior of accepting the full request object. Put another way, if an API adds this annotation to an already-published API, the resulting library change must be backwards-compatible.

Client library generators may also choose to provide this functionality in some cases but not others, as appropriate in the environment. For example, any of the following strategies would be permissible:

  • Providing overloads iff all arguments in the signature are primitives.
  • Providing overloads only for the first of multiple signatures when providing more than one would produce a conflict.
  • Any combination of the above.

In all of these situations, the requirement that the request object is always accepted still applies.

Furthermore, client library generators may choose to support this functionality for a subset of RPC types, those being:

  • Unary
  • Server Streaming
  • Client Streaming
  • Bi-directional Streaming

Method Signatures

An RPC with the google.api.method_signature annotation indicates that an overload with a flattened method signature is desired where supported. The string contains comma-separated arguments, in order. If a field's name contains a period (.) character, this indicates a nested field.

An RPC can provide this annotation more than once to specify multiple signatures. Order matters here: In some situations, it may not be possible to generate an overload for every signature provided. In this situation, client library generators must follow a "first match wins" strategy (generate an overload for the first signature in the conflict set, and drop the rest).

Note: A corollary to this is that it is only guaranteed to be a backwards-compatible change to append method signature annotations.

Required Arguments

Often, certain fields on the request message are consistently required, as described in AIP-203.

While client libraries generally should not perform validation on this (that is the server's role), client libraries may distinguish required arguments in method signatures from optional ones if appropriate for the language. A field is considered required for this purpose if annotated with the google.api.field_behavior annotation value of REQUIRED:

message TranslateTextRequest {
  // The text to translate.
  string q = 1 [(google.api.field_behavior) = REQUIRED];
}

Note: The annotation for field behavior is attached to the field, not the method.

Restrictions

If an RPC lists a nested field in google.api.method_signature (for example, "foo.bar.baz"), none of the individual component fields may be repeated except for the last one (continuing the example, baz could be repeated but foo or bar could not be). Code generators implementing this feature must error with a descriptive error message if encountering a non-terminal repeated field as a field name.

If any fields are required arguments, all required arguments are expected to appear before any optional ones. Code generators implementing this feature should error with a descriptive error message if encountering a required field after an optional one, and must do so if the resulting client library would not be valid.

Compatibility

Removing, reordering or altering an existing google.api.method_signature entry is a breaking change for client libraries. The associated generated method is either removed entirely or its signature is altered, both of which break user code.

Changelog

  • 2020-07-14: Added caveat for supporting some RPC types
  • 2019-09-27: Added a Compatibility section.