github.com/googleapis/api-linter@v1.65.2/docs/rules/0133/method-signature.md (about)

     1  ---
     2  rule:
     3    aip: 133
     4    name: [core, '0133', method-signature]
     5    summary: |
     6      Create RPCs should annotate an appropriate method signature.
     7  permalink: /133/method-signature
     8  redirect_from:
     9    - /0133/method-signature
    10  ---
    11  
    12  # Create methods: Method signature
    13  
    14  This rule enforces that all `Create` standard methods have a
    15  `google.api.method_signature` annotation with an appropriate value, as mandated
    16  in [AIP-133][].
    17  
    18  ## Details
    19  
    20  This rule looks at any method beginning with `Create`, and complains if the
    21  `google.api.method_signature` annotation is missing, or if it is set to an
    22  incorrect value. Additional method signatures, if present, are ignored.
    23  
    24  The correct value is `"parent,{resource},{resource}_id"` if the `{resource}_id`
    25  field exists, and `"parent,{resource}"` otherwise.
    26  
    27  ## Examples
    28  
    29  **Incorrect** code for this rule:
    30  
    31  ```proto
    32  // Incorrect.
    33  rpc CreateBook(CreateBookRequest) returns (Book) {
    34    // A google.api.method_signature annotation should be present.
    35  }
    36  ```
    37  
    38  ```proto
    39  // Incorrect.
    40  rpc CreateBook(CreateBookRequest) returns (Book) {
    41    // Should be "parent,book" or "parent,book,book_id", depending on whether
    42    // a "book_id" field exists.
    43    option (google.api.method_signature) = "publisher,book";
    44  }
    45  ```
    46  
    47  **Correct** code for this rule:
    48  
    49  If the `book_id` field does not exist:
    50  
    51  ```proto
    52  // Correct.
    53  rpc CreateBook(CreateBookRequest) returns (Book) {
    54    option (google.api.method_signature) = "parent,book";
    55  }
    56  ```
    57  
    58  If the `book_id` field exists:
    59  
    60  ```proto
    61  // Correct.
    62  rpc CreateBook(CreateBookRequest) returns (Book) {
    63    option (google.api.method_signature) = "parent,book,book_id";
    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::0133::method-signature=disabled
    74  //     aip.dev/not-precedent: We need to do this because reasons. --)
    75  rpc CreateBook(CreateBookRequest) returns (Book) {
    76    option (google.api.method_signature) = "publisher,book";
    77  }
    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-133]: https://aip.dev/133
    84  [aip.dev/not-precedent]: https://aip.dev/not-precedent