AEP-0131 Linter Rules

Get methods- No HTTP body

Get methods: No HTTP body

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

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
    body: "*"  // This should be absent.
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=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::0131::http-body=disabled
//     api-linter: core::0131::http-method=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{path=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.

Get methods- GET HTTP verb

Get methods: GET HTTP verb

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

Details

This rule looks at any message matching beginning with Get, 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 GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}"  // Should be `get:`.
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=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::0131::http-method=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{path=publishers/*/books/*}"
  };
}

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

Get methods- HTTP URI path field

Get methods: HTTP URI path field

This rule enforces that all Get RPCs map the path field to the HTTP URI, as mandated in AEP-131.

Details

This rule looks at any message matching beginning with Get, and complains if the path variable is not included in the URI. It does check additional bindings if they are present.

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/publishers/*/books/*"  // The `path` field should be extracted.
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=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::0131::http-uri-path=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/publishers/*/books/*"
  };
}

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

Get methods- Method signature

Get methods: Method signature

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

Details

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

Examples

Incorrect code for this rule:

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

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.method_signature) = "book";  // Should be "path".
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.method_signature) = "path";
}

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

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

Get methods- Request message

Get methods: Request message

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

Details

This rule looks at any message matching beginning with Get, 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.
rpc GetBook(GetBookReq) returns (Book) {  // Should be `GetBookRequest`.
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=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::0131::request-message-name=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookReq) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
  };
}

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

Get methods- Field behavior

Get methods: Field behavior

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

Details

This rule looks at any message matching Get*Request and complains if the path 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 GetBookRequest {
  // The `aep.api.field_behavior` annotation should also be included.
  string path = 1 [(aep.api.field_info).resource_reference = {
    type: "library.googleapis.com/Book"
  }];
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
}

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 GetBookRequest {
  // (-- api-linter: core::0131::request-path-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string path = 1 [(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.

Get methods- Name field

Get methods: Name field

This rule enforces that all Get standard methods have a string path field in the request message, as mandated in AEP-131.

Details

This rule looks at any message matching Get*Request and complains if the path field type is not string.

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  bytes path = 1;  // Field type should be `string`.
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  string path = 1;
}

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 GetBookRequest {
  // (-- api-linter: core::0131::request-path-field=disabled
  //     aep.dev/not-precedent: This uses `bytes` for historical reasons. --)
  bytes path = 1;
}

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

Get methods- Resource reference

Get methods: Resource reference

This rule enforces that the (aep.api.field_info).resource_reference on the path field of a Get RPC request message uses type, not child_type, as suggested in AEP-131.

Details

This rule looks at the (aep.api.field_info).resource_reference annotation on the path field of any message matching Get*Request and complains if it does not use a direct type reference.

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  // The `(aep.api.field_info).resource_reference` annotation should be a direct `type`
  // reference.
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.child_type = "library.googleapis.com/Book"
  ];
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
}

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 GetBookRequest {
  // (-- api-linter: core::0131::request-path-reference-type=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.child_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.

Get methods- Resource reference

Get methods: Resource reference

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

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  // The `(aep.api.field_info).resource_reference` annotation should also be included.
  string path = 1 [(aep.api.field_info).field_behavior = FIELD_BEHAVIOR_REQUIRED];
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
}

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 GetBookRequest {
  // (-- api-linter: core::0131::request-path-reference=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string path = 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.

Get methods- Name field

Get methods: Name field

This rule enforces that all Get standard methods have a string path field in the request message, as mandated in AEP-131.

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  string book = 1 [  // Field path should be `path`.
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference.type = "library.googleapis.com/Book"
  ];
}

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::0131::request-path-required=disabled
//     aep.dev/not-precedent: This is named "book" for historical reasons. --)
message GetBookRequest {
  string book = 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.

Get methods- Required fields

Get methods: Required fields

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

Details

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

• string path (AEP-131)

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  // The path of the book to retrieve.
  // Format: publishers/{publisher}/books/{book}
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference = {
      type: "library.googleapis.com/Book"
  }];

  // Non-standard required field.
   google.protobuf.FieldMask read_mask = 2 [(aep.api.field_info).field_behavior = FIELD_BEHAVIOR_REQUIRED];
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  // The path of the book to retrieve.
  // Format: publishers/{publisher}/books/{book}
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference = {
      type: "library.googleapis.com/Book"
  }];

  google.protobuf.FieldMask read_mask = 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 GetBookRequest {
  // The path of the book to retrieve.
  // Format: publishers/{publisher}/books/{book}
  string path = 1 [
    (aep.api.field_behavior) = FIELD_BEHAVIOR_REQUIRED,
    (aep.api.field_info).resource_reference = {
      type: "library.googleapis.com/Book"
  }];

  // (-- api-linter: core::0131::request-required-fields=disabled
  //     aep.dev/not-precedent: We really need this field to be required because
  //     reasons. --)
   google.protobuf.FieldMask read_mask = 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.

Get methods- Unknown fields

Get methods: Unknown fields

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

Details

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

• string path (AEP-131)
• string request_id (AEP-155)
• google.protobuf.FieldMask read_mask (AEP-157)
• View view (AEP-157)

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  string path = 1;
  string library_id = 2;  // Non-standard field.
}

Correct code for this rule:

// Correct.
message GetBookRequest {
  string path = 1;
}

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 GetBookRequest {
  string path = 1;

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

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

Get methods- Response message

Get methods: Response message

This rule enforces that all Get RPCs have a response message of the resource, as mandated in AEP-131.

Details

This rule looks at any message matching beginning with Get, and complains if the name of the corresponding output message does not match the name of the RPC with the prefix Get removed.

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (GetBookResponse) {  // Should be `Book`.
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=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::0131::response-message-path=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (GetBookResponse) {
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
  };
}

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

Get methods- Synonym check

Get methods: Synonym check

This rule enforces that single-resource lookup methods have names starting with Get, as mandated in AEP-131.

Details

This rule looks at any message with names similar to Get, and suggests using Get instead. It complains if it sees the following synonyms:

• Acquire
• Fetch
• Lookup
• Read
• Retrieve

Examples

Incorrect code for this rule:

// Incorrect.
rpc FetchBook(FetchBookRequest) returns (Book) {  // Should be `GetBook`.
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=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::0131::synonyms=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc FetchBook(GetBookReq) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/books/*}"
  };
}

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