github.com/googleapis/api-linter@v1.65.2/docs/rules/0136/declarative-standard-methods-only.md (about)

     1  ---
     2  rule:
     3    aip: 136
     4    name: [core, '0136', standard-methods-only]
     5    summary: Declarative-friendly resources should eschew custom methods.
     6  permalink: /136/standard-methods-only
     7  redirect_from:
     8    - /0136/standard-methods-only
     9  ---
    10  
    11  # Declarative: Standard methods only
    12  
    13  This rule enforces that declarative-friendly resources do not use custom
    14  methods, as discussed in [AIP-136][].
    15  
    16  ## Details
    17  
    18  This rule looks at any method that is not a standard method, and if the
    19  associated resource is a declarative-friendly resource, complains about the use
    20  of a custom method.
    21  
    22  ## Examples
    23  
    24  ### Verb only
    25  
    26  **Incorrect** code for this rule:
    27  
    28  ```proto
    29  // Incorrect.
    30  // Assuming that book is declarative-friendly...
    31  rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
    32    option (google.api.http) = {
    33      post: "/v1/{name=publishers/*/books/*}:checkout"
    34      body: "*"
    35    };
    36  }
    37  ```
    38  
    39  **Correct** code for this rule:
    40  
    41  **Important:** In general, declarative-friendly resources **should not** use
    42  custom methods; however, some declarative-friendly resources **may** have
    43  one-off, truly imperative methods that do not expect support in imperative
    44  tooling. This can be indicated to the linter using the comment shown below.
    45  
    46  ```proto
    47  // Correct.
    48  // (-- Imperative only. --)
    49  rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
    50    option (google.api.http) = {
    51      post: "/v1/{name=publishers/*/books/*}:checkout"
    52      body: "*"
    53    };
    54  }
    55  ```
    56  
    57  ## Disabling
    58  
    59  If you need to violate this rule, use a leading comment above the method.
    60  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    61  
    62  ```proto
    63  // (-- api-linter: core::0136::standard-methods-only=disabled
    64  //     aip.dev/not-precedent: We need to do this because reasons. --)
    65  rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
    66    option (google.api.http) = {
    67      post: "/v1/{name=publishers/*/books/*}:checkout"
    68      body: "*"
    69    };
    70  }
    71  ```
    72  
    73  **Note:** For truly imperative-only methods, you can use the comment form shown
    74  above.
    75  
    76  If you need to violate this rule for an entire file, place the comment at the
    77  top of the file.
    78  
    79  [aip-136]: https://aip.dev/136
    80  [aip.dev/not-precedent]: https://aip.dev/not-precedent
    81  [http-name-variable]: ./http-name-variable.md
    82  [http-parent-variable]: ./http-parent-variable.md