aip-dev / google.aip.dev

API Improvement Proposals. https://aip.dev/
Other
1.08k stars 495 forks source link

[AIP-136] Spec should clarify an exception to the verb in the HTTP URI #1376

Open xyziemba opened 3 months ago

xyziemba commented 3 months ago

General guidance in AIP-136 states that:

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.

However, there's an exception in the Stateless methods section:

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.

This exception, allowing verb and noun, is easy to miss. It would be helpful to update the general guidance with a phrase like "... except for stateless methods as defined in this AIP."