Custom methods: Prepositions

This rule enforces that custom method names do not include most prepositions, as mandated in AIP-136.

Details

This rule looks at any method that is not a standard method, and complains if it sees any of the following words in the method’s name:

  • after
  • at
  • before
  • between
  • but
  • by
  • except
  • for
  • from
  • in
  • including
  • into
  • of
  • over
  • since
  • to
  • toward
  • under
  • upon
  • with
  • within
  • without

Examples

Incorrect code for this rule:

// Incorrect.
// This RPC includes "with", which indicates a potential design concern.
rpc GetBookWithAuthor(GetBookWithAuthorRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=publishers/*/books/*}:getWithAuthor"
  };
}

Sometimes, as in the example above, the inclusion of a preposition indicates a design concern, and the method should be designed differently. In the above case, the right answer is to stick to the standard method.

In other cases, the method may just need to be renamed, but with no major conceptual change:

// Incorrect.
// The "FromLibrary" suffix is vestigial and should be removed.
rpc CheckoutBookFromLibrary(CheckoutBookFromLibraryRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*/books/*}:checkoutFromLibrary"
    body: "*"
  };
}

Correct code for this rule:

// Correct.
rpc CheckoutBook(CheckoutBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*/books/*}:checkout"
    body: "*"
  }
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aip.dev/not-precedent comment explaining why.

// (-- api-linter: core::0136::prepositions=disabled
//     aip.dev/not-precedent: We need to do this because reasons. --)
rpc GetBookWithAuthor(GetBookWithAuthorRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=publishers/*/books/*}:getWithAuthor"
  }
}

If you need to violate this rule for an entire file, place the comment at the top of the file.