github.com/googleapis/api-linter@v1.65.2/docs/rules/0154/declarative-friendly-required.md (about)

     1  ---
     2  rule:
     3    aip: 154
     4    name: [core, '0154', declarative-friendly-required]
     5    summary: Declarative-friendly resources must have an etag field.
     6  permalink: /154/declarative-friendly-required
     7  redirect_from:
     8    - /0154/declarative-friendly-required
     9  ---
    10  
    11  # Required etags
    12  
    13  This rule enforces that declarative-friendly resources have etags, as mandated
    14  in [AIP-154][].
    15  
    16  ## Details
    17  
    18  This rule looks at any resource with a `google.api.resource` annotation that
    19  includes `style: DECLARATIVE_FRIENDLY`, and complains if it lacks a
    20  `string etag` field.
    21  
    22  Additionally, it looks at certain corresponding request messages (e.g.
    23  `DeleteBookRequest`) that _do not_ include the resource, and makes the same
    24  check.
    25  
    26  ## Examples
    27  
    28  **Incorrect** code for this rule:
    29  
    30  ```proto
    31  // Incorrect.
    32  message Book {
    33    option (google.api.resource) = {
    34      type: "library.googleapis.com/Book"
    35      pattern: "publishers/{publisher}/books/{book}"
    36      style: DECLARATIVE_FRIENDLY
    37    };
    38  
    39    string name = 1;
    40    // A string etag field should exist.
    41  }
    42  ```
    43  
    44  ```proto
    45  // Incorrect.
    46  message DeleteBookRequest {
    47    string name = 1 [(google.api.resource_reference) = {
    48      type: "library.googleapis.com/Book"
    49    }];
    50    // A string etag field should exist.
    51  }
    52  ```
    53  
    54  **Correct** code for this rule:
    55  
    56  ```proto
    57  // Correct.
    58  message Book {
    59    option (google.api.resource) = {
    60      type: "library.googleapis.com/Book"
    61      pattern: "publishers/{publisher}/books/{book}"
    62      style: DECLARATIVE_FRIENDLY
    63    };
    64  
    65    string name = 1;
    66    string etag = 2;
    67  }
    68  ```
    69  
    70  ```proto
    71  // Correct.
    72  message DeleteBookRequest {
    73    string name = 1 [(google.api.resource_reference) = {
    74      type: "library.googleapis.com/Book"
    75    }];
    76    string etag = 2;
    77  }
    78  ```
    79  
    80  ## Disabling
    81  
    82  If you need to violate this rule, use a leading comment above the message.
    83  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    84  
    85  ```proto
    86  // (-- api-linter: core::0154::declarative-friendly-required=disabled
    87  //     aip.dev/not-precedent: We need to do this because reasons. --)
    88  message Book {
    89    option (google.api.resource) = {
    90      type: "library.googleapis.com/Book"
    91      pattern: "publishers/{publisher}/books/{book}"
    92      style: DECLARATIVE_FRIENDLY
    93    };
    94  
    95    string name = 1;
    96  }
    97  ```
    98  
    99  **Note:** Violations of declarative-friendly rules should be rare, as tools are
   100  likely to expect strong consistency.
   101  
   102  If you need to violate this rule for an entire file, place the comment at the
   103  top of the file.
   104  
   105  [aip-154]: https://aip.dev/154
   106  [aip.dev/not-precedent]: https://aip.dev/not-precedent