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

     1  ---
     2  rule:
     3    aip: 136
     4    name: [core, '0136', prepositions]
     5    summary: Custom methods must not include prepositions in their names.
     6  permalink: /136/prepositions
     7  redirect_from:
     8    - /0136/prepositions
     9  ---
    10  
    11  # Custom methods: Prepositions
    12  
    13  This rule enforces that custom method names do not include most prepositions,
    14  as mandated in [AIP-136][].
    15  
    16  ## Details
    17  
    18  This rule looks at any method that is not a standard method, and complains if
    19  it sees any of the following words in the method's name:
    20  
    21  {% include prepositions.md %}
    22  
    23  ## Examples
    24  
    25  **Incorrect** code for this rule:
    26  
    27  ```proto
    28  // Incorrect.
    29  // This RPC includes "with", which indicates a potential design concern.
    30  rpc GetBookWithAuthor(GetBookWithAuthorRequest) returns (Book) {
    31    option (google.api.http) = {
    32      get: "/v1/{name=publishers/*/books/*}:getWithAuthor"
    33    };
    34  }
    35  ```
    36  
    37  Sometimes, as in the example above, the inclusion of a preposition indicates a
    38  design concern, and the method should be designed differently. In the above
    39  case, the right answer is to stick to the standard method.
    40  
    41  In other cases, the method may just need to be renamed, but with no major
    42  conceptual change:
    43  
    44  ```proto
    45  // Incorrect.
    46  // The "FromLibrary" suffix is vestigial and should be removed.
    47  rpc CheckoutBookFromLibrary(CheckoutBookFromLibraryRequest) returns (Book) {
    48    option (google.api.http) = {
    49      post: "/v1/{name=publishers/*/books/*}:checkoutFromLibrary"
    50      body: "*"
    51    };
    52  }
    53  ```
    54  
    55  **Correct** code for this rule:
    56  
    57  ```proto
    58  // Correct.
    59  rpc CheckoutBook(CheckoutBookRequest) returns (Book) {
    60    option (google.api.http) = {
    61      post: "/v1/{name=publishers/*/books/*}:checkout"
    62      body: "*"
    63    };
    64  }
    65  ```
    66  
    67  ## Disabling
    68  
    69  If you need to violate this rule, use a leading comment above the method.
    70  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    71  
    72  ```proto
    73  // (-- api-linter: core::0136::prepositions=disabled
    74  //     aip.dev/not-precedent: We need to do this because reasons. --)
    75  rpc GetBookWithAuthor(GetBookWithAuthorRequest) returns (Book) {
    76    option (google.api.http) = {
    77      get: "/v1/{name=publishers/*/books/*}:getWithAuthor"
    78    };
    79  }
    80  ```
    81  
    82  If you need to violate this rule for an entire file, place the comment at the
    83  top of the file.
    84  
    85  [aip-136]: https://aip.dev/136
    86  [aip.dev/not-precedent]: https://aip.dev/not-precedent