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

     1  ---
     2  rule:
     3    aip: 127
     4    name: [core, '0127', http-template-syntax]
     5    summary: |
     6      HTTP patterns should follow the HTTP path template syntax.
     7  permalink: /127/http-template-syntax
     8  redirect_from:
     9    - /0127/http-template-syntax
    10  ---
    11  
    12  # HTTP Pattern Variables
    13  
    14  This rule enforces that HTTP annotation patterns follow the path template syntax
    15  rules, as mandated in [AIP-127][].
    16  
    17  ## Details
    18  
    19  This rule ensures that `google.api.http` patterns adhere to the following
    20  [syntax rules](https://github.com/googleapis/googleapis/blob/83c3605afb5a39952bf0a0809875d41cf2a558ca/google/api/http.proto#L224).
    21  
    22  ## Examples
    23  
    24  **Incorrect** code for this rule:
    25  
    26  ```proto
    27  // Incorrect.
    28  rpc GetBook(GetBookRequest) returns (Book) {
    29      option (google.api.http) = {
    30          // Should start with a leading slash.
    31          get: "v1/{name=shelves/*}"
    32      };
    33  }
    34  ```
    35  
    36  **Incorrect** code for this rule:
    37  
    38  ```proto
    39  // Incorrect.
    40  rpc AddAuthor(AddAuthorRequest) returns (AddAuthorResponse) {
    41      option (google.api.http) = {
    42          // Verb should be marked off with the ':' character.
    43          post: "/v1/{book=publishers/*/books/*}-addAuthor"
    44          body: "*"
    45      };
    46  }
    47  ```
    48  
    49  **Incorrect** code for this rule:
    50  
    51  ```proto
    52  // Incorrect.
    53  rpc CreateBook(CreateBookRequest) returns (Book) {
    54    option (google.api.http) = {
    55      // The triple wildcard ('***') is not a part of the syntax.
    56      post: "/v1/{parent=publishers/***}"
    57      body: "book"
    58    };
    59  }
    60  ```
    61  
    62  **Correct** code for this rule:
    63  
    64  ```proto
    65  // Correct.
    66  rpc GetBook(GetBookRequest) returns (Book) {
    67      option (google.api.http) = {
    68          get: "/v1/{name=shelves/*}"
    69      };
    70  }
    71  ```
    72  
    73  ## Disabling
    74  
    75  If you need to violate this rule, use a leading comment above the field.
    76  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    77  
    78  ```proto
    79  // (-- api-linter: core::0127::http-template-syntax=disabled
    80  //     aip.dev/not-precedent: We need to do this because reasons. --)
    81  rpc GetBook(GetBookRequest) returns (Book) {
    82      option (google.api.http) = {
    83          get: "v1/{name=shelves/*}"
    84      };
    85  }
    86  ```
    87  
    88  If you need to violate this rule for an entire file, place the comment at the
    89  top of the file.
    90  
    91  [aip-127]: https://aip.dev/127
    92  [aip.dev/not-precedent]: https://aip.dev/not-precedent