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

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