github.com/googleapis/api-linter@v1.65.2/docs/rules/0151/lro-response-type.md (about)

     1  ---
     2  rule:
     3    aip: 151
     4    name: [core, '0151', lro-response-type]
     5    summary: LRO methods must have a response type.
     6  permalink: /151/lro-response-type
     7  redirect_from:
     8    - /0151/lro-response-type
     9  ---
    10  
    11  # LRO response type
    12  
    13  This rule enforces that methods returning long-running operations specify a
    14  response type in the `google.longrunning.operation_info` annotation, as
    15  mandated in [AIP-151][].
    16  
    17  ## Details
    18  
    19  This rule looks at any method with a return type of
    20  `google.longrunning.Operation`, and complains if the `response_type` field
    21  `google.longrunning.operation_info` annotation is not present.
    22  
    23  Additionally, it complains if the response type is set to
    24  `google.protobuf.Empty`, and recommends making an blank message instead, to
    25  permit future extensibility. However, methods with names beginning with
    26  `Delete` are exempt from this check (see [AIP-135][]).
    27  
    28  ## Examples
    29  
    30  **Incorrect** code for this rule:
    31  
    32  ```proto
    33  // Incorrect.
    34  rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
    35    option (google.api.http) = {
    36      post: "/v1/{name=publishers/*/books}:write"
    37      body: "*"
    38    };
    39    option (google.longrunning.operation_info) = {
    40      // `response_type` is not provided.
    41      metadata_type: "WriteBookMetadata"
    42    };
    43  }
    44  ```
    45  
    46  ```proto
    47  // Incorrect.
    48  rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
    49    option (google.api.http) = {
    50      post: "/v1/{name=publishers/*/books}:write"
    51      body: "*"
    52    };
    53    option (google.longrunning.operation_info) = {
    54      response_type: "google.protobuf.Empty"  // Should not use `Empty`.
    55      metadata_type: "WriteBookMetadata"
    56    };
    57  }
    58  ```
    59  
    60  **Correct** code for this rule:
    61  
    62  ```proto
    63  // Correct.
    64  rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
    65    option (google.api.http) = {
    66      post: "/v1/{name=publishers/*/books}:write"
    67      body: "*"
    68    };
    69    option (google.longrunning.operation_info) = {
    70      response_type: "WriteBookResponse"
    71      metadata_type: "WriteBookMetadata"
    72    };
    73  }
    74  ```
    75  
    76  ## Disabling
    77  
    78  If you need to violate this rule, use a leading comment above the method.
    79  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    80  
    81  ```proto
    82  // (-- api-linter: core::0151::lro-response-type=disabled
    83  //     aip.dev/not-precedent: We need to do this because reasons. --)
    84  rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
    85    option (google.api.http) = {
    86      post: "/v1/{name=publishers/*/books}:write"
    87      body: "*"
    88    };
    89    option (google.longrunning.operation_info) = {
    90      response_type: "google.protobuf.Empty"
    91      metadata_type: "WriteBookMetadata"
    92    };
    93  }
    94  ```
    95  
    96  If you need to violate this rule for an entire file, place the comment at the
    97  top of the file.
    98  
    99  [aip-135]: https://aip.dev/135
   100  [aip-151]: https://aip.dev/151
   101  [aip.dev/not-precedent]: https://aip.dev/not-precedent