AEP-0132 Linter Rules

List methods- No HTTP body

List methods: No HTTP body

This rule enforces that all List RPCs omit the HTTP body, as mandated in AEP-132.

Details

This rule looks at any message beginning with List, and complains if the HTTP body field is set.

Examples

Incorrect code for this rule:

// Incorrect.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
    body: "*"  // This should be absent.
  };
}

Correct code for this rule:

// Correct.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

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::0132::http-body=disabled
//     api-linter: core::0132::http-method=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "*"
  };
}

Important: HTTP GET requests are unable to have an HTTP body, due to the nature of the protocol. The only valid way to include a body is to also use a different HTTP method (as depicted above).

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

List methods- GET HTTP verb

List methods: GET HTTP verb

This rule enforces that all List RPCs use the GET HTTP verb, as mandated in AEP-132.

Details

This rule looks at any message beginning with List, and complains if the HTTP verb is anything other than GET. It does check additional bindings if they are present.

Examples

Incorrect code for this rule:

// Incorrect.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"  // Should be `get:`.
  };
}

Correct code for this rule:

// Correct.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

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::0132::http-method=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
  };
}

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

List methods- Method signature

List methods: Method signature

This rule enforces that all List standard methods have a google.api.method_signature annotation with a value of "parent", as mandated in AEP-132.

Details

This rule looks at any method beginning with List, and complains if the google.api.method_signature annotation is missing, or if it is set to any value other than "parent". Additional method signatures, if present, are ignored.

Examples

Incorrect code for this rule:

// Incorrect.
rpc ListBooks(ListBooksRequest) returns (Book) {
  // A google.api.method_signature annotation should be present.
}

// Incorrect.
rpc ListBooks(ListBooksRequest) returns (Book) {
  option (google.api.method_signature) = "publisher";  // Should be "parent".
}

Correct code for this rule:

// Correct.
rpc ListBooks(ListBooksRequest) returns (Book) {
  option (google.api.method_signature) = "parent";
}

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::0132::method-signature=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc ListBooks(ListBooksRequest) returns (Book);

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

List methods- Unknown fields

List methods: Unknown fields

This rule enforces that all List standard methods use the correct type for any optional fields described in AEP-132.

Details

This rule looks at the fields in any message matching List*Request and complains if finds fields with the names below that do not have the correct type:

string filter
string order_by
bool show_deleted

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
  BookFilter filter = 4;  // Wrong type; should be a string.
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
  string filter = 4;
}

Disabling

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

message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;

  // (-- api-linter: core::0132::request-field-types=disabled
  //     aep.dev/not-precedent: We really need this field because reasons. --)
  BookFilter filter = 4;
}

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

List methods- Request message

List methods: Request message

This rule enforces that all List RPCs have a request message name of List*Request, as mandated in AEP-132.

Details

This rule looks at any message matching beginning with List, and complains if the name of the corresponding input message does not match the name of the RPC with the suffix Request appended.

Examples

Incorrect code for this rule:

// Incorrect.
// Should be `ListBooksRequest`.
rpc ListBooks(ListBooksReq) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

Correct code for this rule:

// Correct.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

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::0132::request-message-name=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc ListBooks(ListBooksReq) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

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

List methods- Field behavior

List methods: Field behavior

This rule enforces that all List standard methods have aep.api.field_behavior set to FIELD_BEHAVIOR_REQUIRED on their string parent field, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if the parent field does not have a aep.api.field_behavior annotation with a value of FIELD_BEHAVIOR_REQUIRED.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // The `aep.api.field_behavior` annotation should also be included.
  string parent = 1 [(aep.api.field_info).resource_reference = {
    type: "library.googleapis.com/Publisher"
  }];
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Publisher"
  ];
  int32 page_size = 2;
  string page_token = 3;
}

Disabling

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

// (-- api-linter: core::0132::request-parent-behavior=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message ListBooksRequest {
  string parent = 1 [(aep.api.field_info).resource_reference = {
    type: "library.googleapis.com/Publisher"
  }];
  int32 page_size = 2;
  string page_token = 3;
}

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

List methods- Parent field

List methods: Parent field

This rule enforces that all List standard methods have a string parent field in the request message, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if the parent field has any type other than string.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // Field type should be `string`.
  bytes parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

Disabling

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

message ListBooksRequest {
  // (-- api-linter: core::0132::request-parent-field=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  bytes parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

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

List methods- Resource reference

List methods: Resource reference

This rule enforces that all List standard methods have (aep.api.field_info).resource_reference on their string parent field, as mandated in AEP-132.

Details

This rule looks at the parent field of any message matching List*Request and complains if it does not have a (aep.api.field_info).resource_reference annotation.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // The `(aep.api.field_info).resource_reference` annotation should also be included.
  string parent = 1 [(aep.api.field_info).field_behavior = FIELD_BEHAVIOR_REQUIRED];
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Publisher"
  ];
  int32 page_size = 2;
  string page_token = 3;
}

Disabling

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

// (-- api-linter: core::0132::request-parent-reference=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message ListBooksRequest {
  string parent = 1 [(aep.api.field_info).field_behavior = FIELD_BEHAVIOR_REQUIRED];
}

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

List methods- Parent field

List methods: Parent field

This rule enforces that all List standard methods have a string parent field in the request message, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if the parent field is missing.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // Field name should be `parent`.
  string publisher = 1;
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

Disabling

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

// (-- api-linter: core::0132::request-parent-required=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message ListBooksRequest {
  string publisher = 1;
  int32 page_size = 2;
  string page_token = 3;
}

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

List methods- Resource reference

List methods: Resource reference

This rule enforces that all List standard methods reference a resource other than the resource being listed with the (aep.api.field_info).resource_reference on their string parent field, as mandated in AEP-132.

Details

This rule looks at the parent field of any message matching List*Request and complains if the (aep.api.field_info).resource_reference annotation references the resource being listed.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // The `(aep.api.field_info).resource_reference` should not reference the resource
  // being listed.
  string parent = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.child_type = "library.googleapis.com/Book"
  ];
  int32 page_size = 2;
  string page_token = 3;
}

Disabling

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

// (-- api-linter: core::0132::request-parent-valid-reference=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message ListBooksRequest {
  string parent = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
}

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

List methods- Required fields

List methods: Required fields

This rule enforces that all List standard methods do not have unexpected required fields, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if it comes across any required fields other than:

string parent (AEP-132)

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // The parent, which owns this collection of books.
  // Format: publishers/{publisher}
  string parent = 1 [
      (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
      (aep.api.field_info).resource_reference = {
        child_type: "library.googleapis.com/Book"
      }];

  // Non-standard required field.
  int32 page_size = 2 [(aep.api.field_info).field_behavior = FIELD_BEHAVIOR_REQUIRED]
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  // The parent, which owns this collection of books.
  // Format: publishers/{publisher}
  string parent = 1 [
      (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
      (aep.api.field_info).resource_reference = {
        child_type: "library.googleapis.com/Book"
      }];

  int32 page_size = 2 [(aep.api.field_info).field_behavior = OPTIONAL]
}

Disabling

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

message ListBooksRequest {
  // The parent, which owns this collection of books.
  // Format: publishers/{publisher}
  string parent = 1 [
      (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
      (aep.api.field_info).resource_reference = {
        child_type: "library.googleapis.com/Book"
      }];

  // (-- api-linter: core::0132::request-required-fields=disabled
  //     aep.dev/not-precedent: We really need this field to be required because
  // reasons. --)
  int32 page_size = 2 [(aep.api.field_info).field_behavior = FIELD_BEHAVIOR_REQUIRED]
}

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

List methods- show_deleted field

List methods: `show_deleted` field

This rule enforces that all List standard methods have a bool show_deleted field in the request message if the resource supports soft delete, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if the show_deleted field is missing and the corresponding resource has an Undelete method.

Examples

Incorrect code for this rule:

// Incorrect.

service Library {
  ...
  rpc UndeleteBook(UndeleteBookRequest) returns (Book) { ... }
}

// Missing the `bool show_deleted` field.
message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.

service Library {
  ...
  rpc UndeleteBook(UndeleteBookRequest) returns (Book) { ... }
}

message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
  bool show_deleted = 4;
}

Disabling

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

// (-- api-linter: core::0132::request-show-deleted-required=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message ListBooksRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

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

List methods- Unknown fields (Request)

List methods: Unknown fields (Request)

This rule enforces that all List standard methods do not have unexpected fields, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if it comes across any fields other than:

string parent (AEP-132)
int32 max_page_size (AEP-158)
string page_token (AEP-158)
int32 skip (AEP-158)
string filter (AEP-132)
string order_by (AEP-132)
bool show_deleted (AEP-132)
string request_id (AEP-155)
google.protobuf.FieldMask read_mask (AEP-157)
View view (AEP-157)

It only checks field names; it does not validate type correctness. This is handled by other rules, such as request field types.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  string parent = 1;
  int32  max_page_size = 2;
  string page_token = 3;
  string library_id = 4;  // Non-standard field.
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1;
  int32  max_page_size = 2;
  string page_token = 3;
}

Disabling

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

message ListBooksRequest {
  string parent = 1;
  int32  max_page_size = 2;
  string page_token = 3;

  // (-- api-linter: core::0132::request-unknown-fields=disabled
  //     aep.dev/not-precedent: We really need this field because reasons. --)
  string library_id = 4;
}

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

List methods- Parent field resource reference

List methods: Parent field resource reference

This rule enforces that all List standard methods with a string parent field use a proper (aep.api.field_info).resource_reference, that being either a child_type referring to the pagianted resource or a type referring directly to the parent resource, as mandated in AEP-132.

Details

This rule looks at any message matching List*Request and complains if the (aep.api.field_info).resource_reference on the parent field refers to the wrong resource.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksRequest {
  // `child_type` should be used instead of `type` when referring to the
  // paginated resource on a parent field.
  string parent = 1 [(aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"];
  int32 page_size = 2;
  string page_token = 3;
}

Correct code for this rule:

// Correct.
message ListBooksRequest {
  string parent = 1 [(aep.api.field_info).resource_reference.child_type = "library.googleapis.com/Book"];
  int32 page_size = 2;
  string page_token = 3;
}

Disabling

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

message ListBooksRequest {
  // (-- api-linter: core::0132::resource-reference-type=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string parent = 1 [(aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"];
  int32 page_size = 2;
  string page_token = 3;
}

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

List methods- Response message

List methods: Response message

This rule enforces that all List RPCs have a response message name of List*Response, as mandated in AEP-132.

Details

This rule looks at any message matching beginning with List, and complains if the name of the corresponding returned message does not match the name of the RPC with the suffix Response appended.

Examples

Incorrect code for this rule:

// Incorrect.
// Should be `ListBooksResponse`.
rpc ListBooks(ListBooksRequest) returns (Books) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

Correct code for this rule:

// Correct.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

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::0132::response-message-name=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc ListBooks(ListBooksRequest) returns (Books) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}

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

List methods- Unknown fields (Response)

List methods: Unknown fields (Response)

This rule enforces that all List standard methods do not have unexpected fields, as mandated in AEP-132.

Details

This rule looks at any message matching List*Response and complains if it comes across any fields other than:

The resource.
int32/int64 total_size (AEP-132)
string next_page_token (AEP-158)
repeated string unavailable ([AEP-217][])

It only checks field names; it does not validate type correctness or repeated-ness.

Examples

Incorrect code for this rule:

// Incorrect.
message ListBooksResponse {
  repeated Book results = 1;
  string next_page_token = 2;
  string publisher_id = 3;  // Unrecognized field.
}

Correct code for this rule:

// Correct.
message ListBooksResponse {
  repeated Book results = 1;
  string next_page_token = 2;
}

Disabling

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

message ListBooksResponse {
  repeated Book results = 1;
  string next_page_token = 2;
  // (-- api-linter: core::0132::response-unknown-fields=disabled
  //     aep.dev/not-precedent: We really need this field because reasons. --)
  string publisher_id = 3;
}

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

AEP-0132 Linter Rules

List methods: No HTTP body

Details

Examples

Disabling

List methods: GET HTTP verb

Details

Examples

Disabling

List methods: Method signature

Details

Examples

Disabling

List methods: Unknown fields

Details

Examples

Disabling

List methods: Request message

Details

Examples

Disabling

List methods: Field behavior

Details

Examples

Disabling

List methods: Parent field

Details

Examples

Disabling

List methods: Resource reference

Details

Examples

Disabling

List methods: Parent field

Details

Examples

Disabling

List methods: Resource reference

Details

Examples

Disabling

List methods: Required fields

Details

Examples

Disabling

List methods: show_deleted field

Details

Examples

Disabling

List methods: Unknown fields (Request)

Details

Examples

Disabling

List methods: Parent field resource reference

Details

Examples

Disabling

List methods: Response message

Details

Examples

Disabling

List methods: Unknown fields (Response)

Details

Examples

Disabling

List methods: `show_deleted` field