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

     1  ---
     2  rule:
     3    aip: 151
     4    name: [core, '0151', lro-response-reachable]
     5    summary: LRO response messages must be reachable.
     6  permalink: /151/lro-response-reachable
     7  redirect_from:
     8    - /0151/lro-response-reachable
     9  ---
    10  
    11  # LRO: Reachable response types
    12  
    13  This rule enforces that methods returning long-running operations define their
    14  response messages in the same file or a directly-imported file, as mandated in
    15  [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 message designated by the
    21  `response_type` field are not defined in the same file, or a file directly
    22  imported by the file.
    23  
    24  Because these message names are strings, and a string reference does not
    25  require an `import` statement, defining the response types elsewhere can cause
    26  problems for tooling. To prevent this, and also to maintain consistency with
    27  the file layout in [AIP-191][], the linter complains if the message is not
    28  defined in the same file or a file directly imported by the file.
    29  
    30  ## Examples
    31  
    32  **Incorrect** code for this rule:
    33  
    34  In `library_service.proto`:
    35  
    36  ```proto
    37  // Incorrect.
    38  service Library {
    39    rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
    40      option (google.api.http) = {
    41        post: "/v1/{name=publishers/*/books}:write"
    42        body: "*"
    43      };
    44      option (google.longrunning.operation_info) = {
    45        response_type: "WriteBookResponse"
    46        metadata_type: "WriteBookMetadata"
    47      };
    48    }
    49  }
    50  ```
    51  
    52  In `operations.proto`:
    53  
    54  ```proto
    55  // Incorrect.
    56  message WriteBookResponse {
    57    // Should be in the same file or directly imported.
    58  }
    59  
    60  message WriteBookMetadata {
    61    // Should be in the same file or directly imported.
    62  }
    63  ```
    64  
    65  **Correct** code for this rule:
    66  
    67  Same file:
    68  
    69  ```proto
    70  // Correct.
    71  service Library {
    72    rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
    73      option (google.api.http) = {
    74        post: "/v1/{name=publishers/*/books}:write"
    75        body: "*"
    76      };
    77      option (google.longrunning.operation_info) = {
    78        response_type: "WriteBookResponse"
    79        metadata_type: "WriteBookMetadata"
    80      };
    81    }
    82  }
    83  
    84  // Later in the file...
    85  message WriteBookResponse {
    86    // ...
    87  }
    88  
    89  message WriteBookMetadata {
    90    // ...
    91  }
    92  ```
    93  
    94  Separate files:
    95  
    96  In `library_service.proto`:
    97  
    98  ```proto
    99  // Correct.
   100  import "operations.proto";
   101  
   102  service Library {
   103    rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
   104      option (google.api.http) = {
   105        post: "/v1/{name=publishers/*/books}:write"
   106        body: "*"
   107      };
   108      option (google.longrunning.operation_info) = {
   109        response_type: "WriteBookResponse"
   110        metadata_type: "WriteBookMetadata"
   111      };
   112    }
   113  }
   114  ```
   115  
   116  In `operations.proto`:
   117  
   118  ```proto
   119  // Correct.
   120  message WriteBookResponse {
   121    // ...
   122  }
   123  
   124  message WriteBookMetadata {
   125    // ...
   126  }
   127  ```
   128  
   129  ## Disabling
   130  
   131  If you need to violate this rule, use a leading comment above the method.
   132  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
   133  
   134  ```proto
   135  // (-- api-linter: core::0151::lro-response-reachable=disabled
   136  //     aip.dev/not-precedent: We need to do this because reasons. --)
   137  rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
   138    option (google.api.http) = {
   139      post: "/v1/{name=publishers/*/books}:write"
   140      body: "*"
   141    };
   142    option (google.longrunning.operation_info) = {
   143      response_type: "google.protobuf.Empty"
   144      metadata_type: "WriteBookMetadata"
   145    };
   146  }
   147  ```
   148  
   149  If you need to violate this rule for an entire file, place the comment at the
   150  top of the file.
   151  
   152  [aip-151]: https://aip.dev/151
   153  [aip-191]: https://aip.dev/191
   154  [aip.dev/not-precedent]: https://aip.dev/not-precedent