github.com/googleapis/api-linter@v1.65.2/docs/rules/0132/request-show-deleted-required.md (about)

     1  ---
     2  rule:
     3    aip: 132
     4    name: [core, '0132', request-show-deleted-required]
     5    summary: |
     6      List requests must have a `show-deleted` field for resources
     7      supporting soft delete.
     8  permalink: /132/request-show-deleted-required
     9  redirect_from:
    10    - /0132/request-show-deleted-required
    11  ---
    12  
    13  # List methods: `show_deleted` field
    14  
    15  This rule enforces that all `List` standard methods have a `bool show_deleted`
    16  field in the request message if the resource supports soft delete, as mandated
    17  in [AIP-132][].
    18  
    19  ## Details
    20  
    21  This rule looks at any message matching `List*Request` and complains if the
    22  `show_deleted` field is missing and the corresponding resource has an
    23  `Undelete` method.
    24  
    25  ## Examples
    26  
    27  **Incorrect** code for this rule:
    28  
    29  ```proto
    30  // Incorrect.
    31  
    32  service Library {
    33    ...
    34    rpc UndeleteBook(UndeleteBookRequest) returns (Book) { ... }
    35  }
    36  
    37  // Missing the `bool show_deleted` field.
    38  message ListBooksRequest {
    39    string parent = 1;
    40    int32 page_size = 2;
    41    string page_token = 3;
    42  }
    43  ```
    44  
    45  **Correct** code for this rule:
    46  
    47  ```proto
    48  // Correct.
    49  
    50  service Library {
    51    ...
    52    rpc UndeleteBook(UndeleteBookRequest) returns (Book) { ... }
    53  }
    54  
    55  message ListBooksRequest {
    56    string parent = 1;
    57    int32 page_size = 2;
    58    string page_token = 3;
    59    bool show_deleted = 4;
    60  }
    61  ```
    62  
    63  ## Disabling
    64  
    65  If you need to violate this rule, use a leading comment above the message.
    66  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    67  
    68  ```proto
    69  // (-- api-linter: core::0132::request-show-deleted-required=disabled
    70  //     aip.dev/not-precedent: We need to do this because reasons. --)
    71  message ListBooksRequest {
    72    string parent = 1;
    73    int32 page_size = 2;
    74    string page_token = 3;
    75  }
    76  ```
    77  
    78  If you need to violate this rule for an entire file, place the comment at the
    79  top of the file.
    80  
    81  [aip-132]: https://aip.dev/132
    82  [aip.dev/not-precedent]: https://aip.dev/not-precedent