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

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