github.com/googleapis/api-linter@v1.65.2/docs/rules/0127/http-template-pattern.md (about)

     1  ---
     2  rule:
     3    aip: 127
     4    name: [core, '0127', http-template-pattern]
     5    summary: |
     6      HTTP template variable patterns should match the patterns defined by their resources.
     7  permalink: /127/http-template-pattern
     8  redirect_from:
     9    - /0127/http-template-pattern
    10  ---
    11  
    12  # HTTP Pattern Variables
    13  
    14  This rule enforces that any HTTP annotations that reference a resource must
    15  match one of the pattern strings defined by that resource, as mandated in
    16  [AIP-127][].
    17  
    18  ## Details
    19  
    20  This rule ensures that `google.api.http` path template variables that represent
    21  a resource name match one of the resource name patterns of the resource that the
    22  field being referenced represents.
    23  
    24  ## Examples
    25  
    26  **Incorrect** code for this rule:
    27  
    28  ```proto
    29  // Incorrect.
    30  // The template for the `name` variable in the `google.api.http` annotation
    31  // is missing segments from the Book message's `pattern`.
    32  rpc GetBook(GetBookRequest) returns (Book) {
    33      option (google.api.http) = {
    34          get: "v1/{name=shelves/*}"
    35      };
    36  }
    37  message GetBookRequest {
    38      string name = 1 [
    39          (google.api.resource_reference).type = "library.googleapis.com/Book"
    40      ];
    41  }
    42  message Book {
    43      option (google.api.resource) = {
    44          type: "library.googleapis.com/Book"
    45          pattern: "shelves/{shelf}/books/{book}"
    46      };
    47  
    48      // Book resource name.
    49      string name = 1;
    50  }
    51  ```
    52  
    53  **Correct** code for this rule:
    54  
    55  ```proto
    56  // Correct.
    57  rpc GetBook(GetBookRequest) returns (Book) {
    58      option (google.api.http) = {
    59          get: "v1/{name=shelves/*/books/*}"
    60      };
    61  }
    62  message GetBookRequest {
    63      string name = 1 [
    64          (google.api.resource_reference).type = "library.googleapis.com/Book"
    65      ];
    66  }
    67  message Book {
    68      option (google.api.resource) = {
    69          type: "library.googleapis.com/Book"
    70          pattern: "shelves/{shelf}/books/{book}"
    71      };
    72  
    73      // Book resource name.
    74      string name = 1;
    75  }
    76  ```
    77  
    78  ## Disabling
    79  
    80  If you need to violate this rule, use a leading comment above the field.
    81  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    82  
    83  ```proto
    84  // (-- api-linter: core::0127::http-template-pattern=disabled
    85  //     aip.dev/not-precedent: We need to do this because reasons. --)
    86  rpc GetBook(GetBookRequest) returns (Book) {
    87      option (google.api.http) = {
    88          get: "v1/{name=shelves/*}"
    89      };
    90  }
    91  ```
    92  
    93  If you need to violate this rule for an entire file, place the comment at the
    94  top of the file.
    95  
    96  [aip-127]: https://aip.dev/127
    97  [aip.dev/not-precedent]: https://aip.dev/not-precedent