github.com/googleapis/api-linter@v1.65.2/docs/rules/0136/http-uri-suffix.md (about)

     1  ---
     2  rule:
     3    aip: 136
     4    name: [core, '0136', http-uri-suffix]
     5    summary: Custom methods should have a correct URI suffix.
     6  permalink: /136/http-uri-suffix
     7  redirect_from:
     8    - /0136/http-uri-suffix
     9  ---
    10  
    11  # Custom methods: URI suffix
    12  
    13  This rule enforces that custom methods include the custom verb in the REST URI,
    14  as mandated in [AIP-136][].
    15  
    16  ## Details
    17  
    18  This rule looks at any method that is not a standard method, and tries to find
    19  the appropriate suffix at the end of the URI. More specifically:
    20  
    21  - If the URI contains a `name` or `parent` variable, then it expects `:verb` at
    22    the end of the URI.
    23  - Otherwise, it expects `:verbNoun` at the end of the URI.
    24  
    25  **Note:** This rule will not run if the [http-name-variable][] or
    26  [http-parent-variable][] rules raise an issue, as a significant number of
    27  issues raised by this rule are _actually_ violations of one of those.
    28  
    29  ## Examples
    30  
    31  ### Verb only
    32  
    33  **Incorrect** code for this rule:
    34  
    35  ```proto
    36  // Incorrect.
    37  rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
    38    option (google.api.http) = {
    39      // Should end with ":checkout", because the book is implied.
    40      post: "/v1/{name=publishers/*/books/*}:checkoutBook"
    41      body: "*"
    42    };
    43  }
    44  ```
    45  
    46  **Correct** code for this rule:
    47  
    48  ```proto
    49  // Correct.
    50  rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
    51    option (google.api.http) = {
    52      post: "/v1/{name=publishers/*/books/*}:checkout"
    53      body: "*"
    54    };
    55  }
    56  ```
    57  
    58  ### Verb and noun
    59  
    60  **Incorrect** code for this rule:
    61  
    62  ```proto
    63  // Incorrect.
    64  rpc SignContract(SignContractRequest) returns (SignContractResponse) {
    65    option (google.api.http) = {
    66      // Should end with ":signContract", because contract is not implied.
    67      post: "/v1/{publisher=publishers/*}:sign"
    68      body: "*"
    69    };
    70  }
    71  ```
    72  
    73  **Correct** code for this rule:
    74  
    75  ```proto
    76  // Correct.
    77  rpc SignContract(SignContractRequest) returns (SignContractResponse) {
    78    option (google.api.http) = {
    79      post: "/v1/{publisher=publishers/*}:signContract"
    80      body: "*"
    81    };
    82  }
    83  ```
    84  
    85  ## Known limitations
    86  
    87  This rule naïvely assumes that the verb is always one word (the "noun" may be
    88  any number of words; they often include adjectives). This may cause some false
    89  positives, and the rule **may** be disabled in these situations.
    90  
    91  **Note:** Before disabling the rule, consider whether the verb is properly
    92  represented as a single word. A common occurrence here is for words like
    93  "Signup", "Rollout", etc., which **should** prefer their single-word form.
    94  
    95  ## Disabling
    96  
    97  If you need to violate this rule, use a leading comment above the method.
    98  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    99  
   100  ```proto
   101  // (-- api-linter: core::0136::http-uri-suffix=disabled
   102  //     aip.dev/not-precedent: We need to do this because reasons. --)
   103  rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
   104    option (google.api.http) = {
   105      post: "/v1/{name=publishers/*/books/*}:checkoutBook"
   106      body: "*"
   107    };
   108  }
   109  ```
   110  
   111  If you need to violate this rule for an entire file, place the comment at the
   112  top of the file.
   113  
   114  [aip-136]: https://aip.dev/136
   115  [aip.dev/not-precedent]: https://aip.dev/not-precedent
   116  [http-name-variable]: ./http-name-variable.md
   117  [http-parent-variable]: ./http-parent-variable.md