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

     1  ---
     2  rule:
     3    aip: 127
     4    name: [core, '0127', http-annotation]
     5    summary: HTTP annotations must be present on non-streaming methods.
     6  permalink: /127/http-annotation
     7  redirect_from:
     8    - /0127/http-annotation
     9  ---
    10  
    11  # HTTP URI case
    12  
    13  This rule enforces that the HTTP annotation is present on all
    14  non-bidi-streaming methods and absent on streaming methods, as mandated in
    15  [AIP-127](http://aip.dev/127).
    16  
    17  ## Details
    18  
    19  This rule scans all methods that a `google.api.http` annotation is present on
    20  all non-streaming methods, as well as methods that only use streaming in one
    21  direction. It complains if an annotation is not found.
    22  
    23  For bidi-streaming methods, it complains if a `google.api.http` annotation _is_
    24  found.
    25  
    26  ## Examples
    27  
    28  ### Unary methods
    29  
    30  **Incorrect** code for this rule:
    31  
    32  ```proto
    33  // Incorrect.
    34  rpc GetBook(GetBookRequest) returns (Book);  // Missing `google.api.http`.
    35  ```
    36  
    37  **Correct** code for this rule:
    38  
    39  ```proto
    40  // Correct.
    41  rpc GetBook(GetBookRequest) returns (Book) {
    42    option (google.api.http) = {
    43      get: "/v1/{name=publishers/*/books/*}"
    44    };
    45  }
    46  ```
    47  
    48  ### Bidi-streaming methods
    49  
    50  **Incorrect** code for this rule:
    51  
    52  ```proto
    53  // Incorrect.
    54  rpc EditBook(stream EditBookRequest) returns (stream EditBookResponse) {
    55    option (google.api.http) = {  // HTTP/1.1 not supported for bi-di streaming.
    56      post: "/v1/{name=publishers/*/books/*}:edit"
    57      body: "*"
    58    };
    59  }
    60  ```
    61  
    62  **Correct** code for this rule:
    63  
    64  ```proto
    65  // Correct.
    66  rpc EditBook(stream EditBookRequest) returns (stream EditBookResponse);
    67  ```
    68  
    69  ## Disabling
    70  
    71  If you need to violate this rule, use a leading comment above the method.
    72  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    73  
    74  ```proto
    75  // (-- api-linter: core::0127::http-annotation=disabled
    76  //     aip.dev/not-precedent: We need to do this because reasons. --)
    77  rpc GetBook(GetBookRequest) returns (Book);
    78  ```
    79  
    80  If you need to violate this rule for an entire file, place the comment at the
    81  top of the file.
    82  
    83  [aip-127]: https://aip.dev/127
    84  [aip.dev/not-precedent]: https://aip.dev/not-precedent