github.com/googleapis/api-linter@v1.65.2/docs/rules/0156/forbidden-methods.md (about)

     1  ---
     2  rule:
     3    aip: 156
     4    name: [core, '0156', forbidden-methods]
     5    summary: Singletons must not define Create, or Delete methods.
     6  permalink: /156/forbidden-methods
     7  redirect_from:
     8    - /0156/forbidden-methods
     9  ---
    10  
    11  # Singletons: Forbidden methods
    12  
    13  This rule enforces that singleton resources do not define `Create`, or `Delete`
    14  methods, as mandated in [AIP-156][].
    15  
    16  ## Details
    17  
    18  This rule looks at any message with a `name` variable in the URI where the name
    19  ends in anything other than `*`. It assumes that this is a method operating on
    20  a singleton resource, and complains if the method is a `Create`, or `Delete`
    21  standard method.
    22  
    23  ## Examples
    24  
    25  **Incorrect** code for this rule:
    26  
    27  ```proto
    28  // Incorrect.
    29  rpc GetSettings(GetSettingsRequest) returns (Settings) {
    30    option (google.api.http) = {
    31      get: "/v1/{name=publishers/*/settings}"
    32    };
    33  }
    34  
    35  rpc UpdateSettings(UpdateSettingsRequest) returns (Settings) {
    36    option (google.api.http) = {
    37      patch: "/v1/{settings.name=publishers/*/settings}"
    38      body: "settings"
    39    };
    40  }
    41  
    42  // This method should not exist. The settings should be implicitly created
    43  // when the publisher is created.
    44  rpc CreateSettings(CreateSettingsRequest) returns (Settings) {
    45    option (google.api.http) = {
    46      post: "/v1/{name=publishers/*/settings}"
    47      body: "settings"
    48    };
    49  }
    50  
    51  // This method should not exist. The settings should always implicitly exist.
    52  rpc DeleteSettings(DeleteSettingsRequest) returns (google.protobuf.Empty) {
    53    option (google.api.http) = {
    54      delete: "/v1/{name=publishers/*/settings}"
    55    };
    56  }
    57  ```
    58  
    59  **Correct** code for this rule:
    60  
    61  ```proto
    62  // Correct.
    63  rpc GetSettings(GetSettingsRequest) returns (Settings) {
    64    option (google.api.http) = {
    65      get: "/v1/{name=publishers/*/settings}"
    66    };
    67  }
    68  
    69  rpc UpdateSettings(UpdateSettingsRequest) returns (Settings) {
    70    option (google.api.http) = {
    71      patch: "/v1/{settings.name=publishers/*/settings}"
    72      body: "settings"
    73    };
    74  }
    75  ```
    76  
    77  ## Disabling
    78  
    79  If you need to violate this rule, use a leading comment above the method.
    80  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    81  
    82  ```proto
    83  rpc GetSettings(GetSettingsRequest) returns (Settings) {
    84    option (google.api.http) = {
    85      get: "/v1/{name=publishers/*/settings}"
    86    };
    87  }
    88  
    89  rpc UpdateSettings(UpdateSettingsRequest) returns (Settings) {
    90    option (google.api.http) = {
    91      patch: "/v1/{settings.name=publishers/*/settings}"
    92      body: "settings"
    93    };
    94  }
    95  
    96  // (-- api-linter: core::0156::forbidden-methods=disabled
    97  //     aip.dev/not-precedent: We need to do this because reasons. --)
    98  rpc CreateSettings(CreateSettingsRequest) returns (Settings) {
    99    option (google.api.http) = {
   100      post: "/v1/{name=publishers/*/settings}"
   101      body: "settings"
   102    };
   103  }
   104  
   105  // (-- api-linter: core::0156::forbidden-methods=disabled
   106  //     aip.dev/not-precedent: We need to do this because reasons. --)
   107  rpc DeleteSettings(DeleteSettingsRequest) returns (google.protobuf.Empty) {
   108    option (google.api.http) = {
   109      delete: "/v1/{name=publishers/*/settings}"
   110    };
   111  }
   112  ```
   113  
   114  If you need to violate this rule for an entire file, place the comment at the
   115  top of the file.
   116  
   117  [aip-156]: https://aip.dev/156
   118  [aip.dev/not-precedent]: https://aip.dev/not-precedent