Clarify method naming

[kaibolay]

Names for resource-base and collection-based methods can be a verb only.

[kaibolay]

The examples "/v1/{name=publishers/*/books/*}:archive" and ""/v1/{parent=publishers/*}/books:sort" both use only a verb as the method name. Only "/v1/{project=projects/*}:translateText" uses verb+noun.

[noahdietz]

Hi @kaibolay thanks for the proposed change.

Can I ask for the context of the proposed change? The existing guidance is by design, not a mistake needing clarification, so it would be great to understand the motivation for the change. Thanks!

[noahdietz]

Hi @kaibolay thanks for the proposed change.

Can I ask for the context of the proposed change? The existing guidance is by design, not a mistake needing clarification, so it would be great to understand the motivation for the change. Thanks!

Apologies, I opened this prior to your PR comment with an example, and didn't refresh before hitting send.

[noahdietz]

The examples "/v1/{name=publishers/*/books/*}:archive" and ""/v1/{parent=publishers/*}/books:sort" both use only a verb as the method name. Only "/v1/{project=projects/*}:translateText" uses verb+noun.

Right, ok, so I think see where things are confusing, and totally see how we got here.

The following guidance:

The name of the method should be a verb followed by a noun.

Is referring to the rpc name in proto - method == rpc. While it might not be obvious, we define an API Method to be as follows:

An individual operation within an API. It is typically represented in Protocol Buffers by an rpc definition, and is mapped to a function in the API in most programming languages.

The examples you've mentioned are referring to the HTTP "custom method suffix" that AIP-136 standardized for differentiating a custom method from a standard method on the same Resource path. This is covered by the following existing guidance:

• The HTTP URI must use a : character followed by the custom verb
  (:archive in the above example), and the verb in the URI must match the
  verb in the name of the RPC.
  • If word separation is required, camelCase must be used.

and for stateless methods:

• The URI should place both the verb and noun after the : separator
  (avoid a "faux collection key" in the URI in this case, as there is no
  collection). For example, :translateText is preferable to text:translate.

Does that clarify things?

[kaibolay]

Does that clarify things?

Yes, definitely. Thanks!