github.com/googleapis/api-linter@v1.65.2/docs/rules/0135/response-message-name.md (about)

     1  ---
     2  rule:
     3    aip: 135
     4    name: [core, '0135', response-message-name]
     5    summary: Delete methods must return Empty or the resource.
     6  permalink: /135/response-message-name
     7  redirect_from:
     8    - /0135/response-message-name
     9  ---
    10  
    11  # Delete methods: Response message
    12  
    13  This rule enforces that all `Delete` RPCs have a response message of
    14  `google.protobuf.Empty` or the resource, as mandated in [AIP-135][].
    15  
    16  ## Details
    17  
    18  This rule looks at any message matching beginning with `Delete`, and complains
    19  if the name of the corresponding output message is not one of:
    20  
    21  - `google.protobuf.Empty`
    22  - The name of the RPC with the prefix `Delete` removed.
    23  
    24  It also permits a response of `google.longrunning.Operation`; in this case, it
    25  checks the `response_type` in the `google.longrunning.operation_info`
    26  annotation and ensures that _it_ corresponds to either `google.protobuf.Empty`
    27  or the name of the RPC with the prefix `Delete` removed.
    28  
    29  ## Examples
    30  
    31  ### Standard
    32  
    33  **Incorrect** code for this rule:
    34  
    35  ```proto
    36  // Incorrect.
    37  // Should be `google.protobuf.Empty` or the resource.
    38  rpc DeleteBook(DeleteBookRequest) returns (DeleteBookResponse) {
    39    option (google.api.http) = {
    40      delete: "/v1/{name=publishers/*/books/*}"
    41    };
    42  }
    43  ```
    44  
    45  **Correct** code for this rule:
    46  
    47  ```proto
    48  // Correct.
    49  rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
    50    option (google.api.http) = {
    51      delete: "/v1/{name=publishers/*/books/*}"
    52    };
    53  }
    54  ```
    55  
    56  ```proto
    57  // Correct.
    58  rpc DeleteBook(DeleteBookRequest) returns (Book) {
    59    option (google.api.http) = {
    60      delete: "/v1/{name=publishers/*/books/*}"
    61    };
    62  }
    63  ```
    64  
    65  **Important:** For declarative-friendly resources, only the resource is
    66  permitted as a return type (and therefore only the second example is valid).
    67  
    68  ### Long-running operation
    69  
    70  **Incorrect** code for this rule:
    71  
    72  ```proto
    73  // Incorrect.
    74  rpc DeleteBook(DeleteBookRequest) returns (google.longrunning.Operation) {
    75    option (google.api.http) = {
    76      delete: "/v1/{name=publishers/*/books/*}"
    77    };
    78    option (google.longrunning.operation_info) = {
    79      // Should be "google.protobuf.Empty" or "Book".
    80      response_type: "DeleteBookResponse"
    81      metadata_type: "DeleteBookMetadata"
    82    };
    83  }
    84  ```
    85  
    86  **Correct** code for this rule:
    87  
    88  ```proto
    89  // Correct.
    90  rpc DeleteBook(DeleteBookRequest) returns (google.longrunning.Operation) {
    91    option (google.api.http) = {
    92      delete: "/v1/{name=publishers/*/books/*}"
    93    };
    94    option (google.longrunning.operation_info) = {
    95      response_type: "google.protobuf.Empty"
    96      metadata_type: "DeleteBookMetadata"
    97    };
    98  }
    99  ```
   100  
   101  ```proto
   102  // Correct.
   103  rpc DeleteBook(DeleteBookRequest) returns (google.longrunning.Operation) {
   104    option (google.api.http) = {
   105      delete: "/v1/{name=publishers/*/books/*}"
   106    };
   107    option (google.longrunning.operation_info) = {
   108      response_type: "Book"
   109      metadata_type: "DeleteBookMetadata"
   110    };
   111  }
   112  ```
   113  
   114  ## Disabling
   115  
   116  If you need to violate this rule, use a leading comment above the method.
   117  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
   118  
   119  ```proto
   120  // (-- api-linter: core::0135::response-message-name=disabled
   121  //     aip.dev/not-precedent: We need to do this because reasons. --)
   122  rpc DeleteBook(DeleteBookRequest) returns (DeleteBookResponse) {
   123    option (google.api.http) = {
   124      delete: "/v1/{name=publishers/*/books/*}"
   125    };
   126  }
   127  ```
   128  
   129  If you need to violate this rule for an entire file, place the comment at the
   130  top of the file.
   131  
   132  [aip-135]: https://aip.dev/135
   133  [aip.dev/not-precedent]: https://aip.dev/not-precedent