AEP-0136 Linter Rules

Declarative- Standard methods only

Declarative: Standard methods only

This rule enforces that declarative-friendly resources do not use custom methods, as discussed in AEP-136.

Details

This rule looks at any method that is not a standard method, and if the associated resource is a declarative-friendly resource, complains about the use of a custom method.

Examples

Verb only

Incorrect code for this rule:

// Incorrect.
// Assuming that book is declarative-friendly...
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}:checkout"
    body: "*"
  };
}

Correct code for this rule:

Important: In general, declarative-friendly resources should not use custom methods; however, some declarative-friendly resources may have one-off, truly imperative methods that do not expect support in imperative tooling. This can be indicated to the linter using the comment shown below.

// Correct.
// (-- Imperative only. --)
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}:checkout"
    body: "*"
  };
}

Disabling

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

// (-- api-linter: core::0136::standard-methods-only=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}:checkout"
    body: "*"
  };
}

Note: For truly imperative-only methods, you can use the comment form shown above.

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

Custom methods- HTTP body

Custom methods: HTTP body

This rule enforces that all custom methods set the HTTP body to *, as advised in AEP-136.

Details

This rule looks at any method that is not a standard method, and complains if the HTTP body field is not set to "*". It also permits the path of the resource.

Examples

Incorrect code for this rule:

// Incorrect.
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books}:checkout"
    // `body: "*"` should be included.
  };
}

Correct code for this rule:

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

Disabling

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

// (-- api-linter: core::0136::http-body=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books}:checkout"
  };
}

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

Custom methods- HTTP method

Custom methods: HTTP method

This rule enforces that all custom methods use the POST or GET HTTP verbs, as mandated in AEP-136.

Details

This rule looks at any method that is not a standard method, and complains if the HTTP verb is anything other than POST or GET. It does check additional bindings if they are present.

Examples

Incorrect code for this rule:

// Incorrect.
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    put: "/v1/{path=publishers/*/books/*}:checkout"  // Should be `post:`.
    body: "*"
  };
}

Correct code for this rule:

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

Disabling

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

// (-- api-linter: core::0136::http-method=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
  option (google.api.http) = {
    put: "/v1/{path=publishers/*/books/*}:checkout"
    body: "*"
  };
}

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

Custom methods- Prepositions

Custom methods: Prepositions

This rule enforces that custom method names do not include most prepositions, as mandated in AEP-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:

{% include prepositions.md %}

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/{path=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/{path=publishers/*/books/*}:checkoutFromLibrary"
    body: "*"
  };
}

Correct code for this rule:

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

Disabling

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

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

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

Custom methods- Verb and noun

Custom methods: Verb and noun

This rule enforces that custom methods are named according to VerbNoun, as mandated in AEP-136.

Details

This is difficult to enforce without a dictionary (likely not worth it), so this rule just attempts to catch common, easy to spot errors. It complains if:

• The method name is one word.

Examples

Single word method

Incorrect code for this rule:

// Incorrect.
rpc Checkout(CheckoutRequest) returns (CheckoutResponse) {  // No noun.
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}:checkout"
    body: "*"
  };
}

Correct code for this rule:

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

Disabling

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

// (-- api-linter: core::0136::verb-noun=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc Checkout(CheckoutRequest) returns (CheckoutResponse) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}:checkout"
    body: "*"
  };
}

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