github.com/googleapis/api-linter@v1.65.2/docs/rules/0133/http-uri-resource.md (about)

     1  ---
     2  rule:
     3    aip: 133
     4    name: [core, '0133', http-uri-resource]
     5    summary: The collection where the resource is added should map to the URI path.
     6  permalink: /133/http-uri-resource
     7  redirect_from:
     8    - /0133/http-uri-resource
     9  ---
    10  
    11  # Create methods: HTTP URI resource
    12  
    13  This rule enforces that the collection identifier used in the URI path is
    14  provided in the definition for the resource being created, as mandated in
    15  [AIP-133][].
    16  
    17  ## Details
    18  
    19  This rule looks at any method beginning with `Create`, and retrieves the URI
    20  path from the `google.api.http` annotation on the method. The final segment of
    21  the URI is extracted as the `collection_identifier`.
    22  
    23  This rule then ensures that each `google.api.http` annotation on the method's
    24  return type contains the string `"{collection_identifier}/"` in each `pattern`.
    25  
    26  ## Examples
    27  
    28  **Incorrect** code for this rule:
    29  
    30  ```proto
    31  // Incorrect.
    32  rpc CreateBook(CreateBookRequest) returns (Book) {
    33    option (google.api.http) = {
    34      // There collection identifier should appear after the final `/` in the URI.
    35      post: "/v1/"
    36      body: "book"
    37    };
    38  }
    39  
    40  message Book {
    41    option (google.api.resource) = {
    42      type: "library.googleapis.com/Book"
    43      pattern: "publishers/{publisher}/books/{book}"
    44    };
    45  }
    46  ```
    47  
    48  **Incorrect** code for this rule:
    49  
    50  ```proto
    51  // Incorrect.
    52  rpc CreateBook(CreateBookRequest) returns (Book) {
    53    option (google.api.http) = {
    54      post: "/v1/{parent=publishers/*}/books"
    55      body: "book"
    56    };
    57  }
    58  
    59  message Book {
    60    option (google.api.resource) = {
    61      type: "library.googleapis.com/Book"
    62      // The pattern does not contain the collection identifier `books`.
    63      pattern: "publishers/{publisher}"
    64    };
    65  }
    66  ```
    67  
    68  **Correct** code for this rule:
    69  
    70  ```proto
    71  // Correct.
    72  rpc CreateBook(CreateBookRequest) returns (Book) {
    73    option (google.api.http) = {
    74      post: "/v1/{parent=publishers/*}/books"
    75      body: "book"
    76    };
    77  }
    78  
    79  message Book {
    80    option (google.api.resource) = {
    81      type: "library.googleapis.com/Book"
    82      pattern: "publishers/{publisher}/books/{book}"
    83    };
    84  }
    85  ```
    86  
    87  ## Disabling
    88  
    89  If you need to violate this rule, use a leading comment above the method.
    90  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    91  
    92  ```proto
    93  // (-- api-linter: core::0133::http-uri-resource=disabled
    94  //     aip.dev/not-precedent: We need to do this because reasons. --)
    95  rpc CreateBook(CreateBookRequest) returns (Book) {
    96    option (google.api.http) = {
    97      post: "/v1/"
    98      body: "book"
    99    };
   100  }
   101  ```
   102  
   103  If you need to violate this rule for an entire file, place the comment at the
   104  top of the file.
   105  
   106  [aip-133]: https://aip.dev/133
   107  [aip.dev/not-precedent]: https://aip.dev/not-precedent