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

     1  ---
     2  rule:
     3    aip: 136
     4    name: [core, '0136', http-name-variable]
     5    summary:
     6      Custom methods should only use `name` if the RPC noun matches the resource.
     7  permalink: /136/http-name-variable
     8  redirect_from:
     9    - /0136/http-name-variable
    10  ---
    11  
    12  **Important:** This rule has been temporarily disabled as it does not match any
    13  AIP guidance. See discussion [here][https://github.com/aip-dev/google.aip.dev/issues/955].
    14  
    15  # Custom methods: HTTP name variable
    16  
    17  This rule enforces that custom methods only use the `name` variable if the RPC
    18  noun matches the resource, as mandated in [AIP-136][].
    19  
    20  ## Details
    21  
    22  This rule looks at custom methods and, if the URI contains a `name` variable,
    23  it ensures that the RPC name ends with the same text as the final component in
    24  the URI (after adjusting for case).
    25  
    26  ## Examples
    27  
    28  **Incorrect** code for this rule:
    29  
    30  ```proto
    31  // Incorrect.
    32  // The variable should be "book", or the RPC name should change.
    33  rpc WritePage(WritePageRequest) return (WritePageResponse) {
    34    option (google.api.http) = {
    35      post: "/v1/{name=publishers/*/books/*}:writePage"
    36      body: "*"
    37    };
    38  }
    39  ```
    40  
    41  **Correct** code for this rule:
    42  
    43  ```proto
    44  // Correct.
    45  // If Page is not a first-class resource, use `book` as the variable name
    46  // and a verb-noun suffix.
    47  rpc WritePage(WritePageRequest) return (WritePageResponse) {
    48    option (google.api.http) = {
    49      post: "/v1/{book=publishers/*/books/*}:writePage"
    50      body: "*"
    51    };
    52  }
    53  ```
    54  
    55  ```proto
    56  // Correct.
    57  // If Page is a first-class, already-created resource, use `name` as the
    58  // variable name and a verb-only suffix.
    59  rpc WritePage(WritePageRequest) return (WritePageResponse) {
    60    option (google.api.http) = {
    61      post: "/v1/{name=publishers/*/books/*/pages/*}:write"
    62      body: "*"
    63    };
    64  }
    65  ```
    66  
    67  See also the [http-parent-variable][] rule (for first-class resources that are
    68  created by the custom RPC).
    69  
    70  ## Disabling
    71  
    72  If you need to violate this rule, use a leading comment above the method.
    73  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    74  
    75  ```proto
    76  // (-- api-linter: core::0136::http-name-variable=disabled
    77  //     aip.dev/not-precedent: We need to do this because reasons. --)
    78  rpc WritePage(WritePageRequest) return (WritePageResponse) {
    79    option (google.api.http) = {
    80      post: "/v1/{name=publishers/*/books/*}:writePage"
    81      body: "*"
    82    };
    83  }
    84  ```
    85  
    86  If you need to violate this rule for an entire file, place the comment at the
    87  top of the file.
    88  
    89  [aip-136]: https://aip.dev/136
    90  [aip.dev/not-precedent]: https://aip.dev/not-precedent
    91  [http-parent-variable]: ./http-parent-variable.md