AEP-0133 Linter Rules

Create methods- HTTP body

Create methods: HTTP body

This rule enforces that all Create RPCs set the HTTP body to the resource, as mandated in AEP-133.

Details

This rule looks at any message matching beginning with Create, and complains if the HTTP body field is not set to the resource being created.

Note that any additional_bindings need their own body field.

Examples

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "*"  // This should be "book".
  };
}

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
    additional_bindings: {
      post: "/v1/books"
      // There should be a "body" here too.
    }
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
    additional_bindings: {
      post: "/v1/books"
      body: "book"
    }
  };
}

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

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

Create methods- POST HTTP verb

Create methods: POST HTTP verb

This rule enforces that all Create RPCs use the POST HTTP verb, as mandated in AEP-133.

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    put: "/v1/{parent=publishers/*}/books"  // Should be `post:`.
    body: "book"
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

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::0133::http-method=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    put: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

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

Create methods- HTTP URI parent field

Create methods: HTTP URI parent field

This rule enforces that all Create RPCs map the parent field to the HTTP URI, as mandated in AEP-133.

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/publishers/*/books"  // The `parent` field should be extracted.
    body: "book"
  };
}

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    // The only variable should be `parent`.
    post: "/v1/{parent=publishers/*}/{book=books/*}"
    body: "*"
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

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::0133::http-uri-parent=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/publishers/*/books"
    body: "book"
  };
}

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

Create methods- HTTP URI resource

Create methods: HTTP URI resource

This rule enforces that the collection identifier used in the URI path is provided in the definition for the resource being created, as mandated in AEP-133.

Details

This rule looks at any method beginning with Create, and retrieves the URI path from the google.api.http annotation on the method. The final segment of the URI is extracted as the collection_identifier.

This rule then ensures that each google.api.http annotation on the method’s return type contains the string "{collection_identifier}/" in each pattern.

Examples

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    // There collection identifier should appear after the final `/` in the URI.
    post: "/v1/"
    body: "book"
  };
}

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };
}

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    // The pattern does not contain the collection identifier `books`.
    pattern: "publishers/{publisher}"
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };
}

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::0133::http-uri-resource=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/"
    body: "book"
  };
}

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

Create methods- Method signature

Create methods: Method signature

This rule enforces that all Create standard methods have a google.api.method_signature annotation with an appropriate value, as mandated in AEP-133.

Details

This rule looks at any method beginning with Create, and complains if the google.api.method_signature annotation is missing, or if it is set to an incorrect value. Additional method signatures, if present, are ignored.

The correct value is "parent,{resource},{resource}_id" if the {resource}_id field exists, and "parent,{resource}" otherwise.

Examples

Incorrect code for this rule:

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

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  // Should be "parent,book" or "parent,book,book_id", depending on whether
  // a "book_id" field exists.
  option (google.api.method_signature) = "publisher,book";
}

Correct code for this rule:

If the book_id field does not exist:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.method_signature) = "parent,book";
}

If the book_id field exists:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.method_signature) = "parent,book,book_id";
}

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::0133::method-signature=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.method_signature) = "publisher,book";
}

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

Client-specified IDs

Client-specified IDs

This rule enforces that declarative-friendly create methods include a client-specified ID field, as mandated in AEP-133.

Details

This rule looks at any Create method connected to a resource and complains if it lacks a client-specified ID (e.g. string book_id) field.

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBookRequest {
  string parent = 1 [(google.api.resource_reference) = {
    child_type: "library.googleapis.com/Book"
  }];

  Book book = 2;

  // A `string book_id` field should exist.
}

Correct code for this rule:

// Correct.
message CreateBookRequest {
  string parent = 1 [(google.api.resource_reference) = {
    child_type: "library.googleapis.com/Book"
  }];

  string id = 2;

  Book book = 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::0133::request-id-field=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message CreateBookRequest {
  string parent = 1 [(google.api.resource_reference) = {
    child_type: "library.googleapis.com/Book"
  }];

  Book book = 2;
}

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

Create methods- Request message

Create methods: Request message

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

Details

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

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

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

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

Create methods- Field behavior

Create methods: Field behavior

This rule enforces that all Create standard methods have google.api.field_behavior set to REQUIRED on their string parent field, as mandated in AEP-133.

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBooksRequest {
  // The `google.api.field_behavior` annotation should also be included.
  string parent = 1 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Publisher"
  }];
  Book book = 2 [(google.api.field_behavior) = REQUIRED];
}

Correct code for this rule:

// Correct.
message CreateBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "library.googleapis.com/Publisher"
  ];
  Book book = 2 [(google.api.field_behavior) = REQUIRED];
}

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 CreateBooksRequest {
  // (-- api-linter: core::0133::request-parent-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string parent = 1 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Publisher"
  }];
  Book book = 2 [(google.api.field_behavior) = REQUIRED];
}

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

Create methods- Parent field

Create methods: Parent field

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

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
message GetBookRequest {
  // Field type should be `string`.
  bytes parent = 1;
  Book book = 2;
  string book_id = 3;
}

Correct code for this rule:

// Correct.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string book_id = 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 CreateBookRequest {
  // (-- api-linter: core::0133::request-parent-field=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  bytes parent = 1;
  Book book = 2;
  string book_id = 3;
}

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

Create methods- Parent field

Create methods: Parent field

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

Details

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

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBookRequest {
  // Field name should be `parent`.
  string publisher = 1;
  Book book = 2;
  string book_id = 3;
}

Correct code for this rule:

// Correct.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string book_id = 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::0133::request-parent-required=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message CreateBookRequest {
  string publisher = 1;
  Book book = 2;
  string book_id = 3;
}

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

Create methods- Required fields

Create methods: Required fields

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

Details

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

• string parent (AEP-133)
• {Resource} {resource} (AEP-133)
• string {resource}_id (AEP-133)

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string book_id = 3;
  // Non-standard required field.
  string validate_only = 4 [(google.api.field_behavior) = REQUIRED];
}

Correct code for this rule:

// Correct.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string id = 3;
  string validate_only = 4 [(google.api.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 CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string id = 3;

  // (-- api-linter: core::0133::request-required-fields=disabled
  //     aep.dev/not-precedent: We really need this field to be required because
  // reasons. --)
  string validate_only = 4 [(google.api.field_behavior) = REQUIRED];
}

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

Create methods- Field behavior

Create methods: Field behavior

This rule enforces that all Create standard methods have google.api.field_behavior set to REQUIRED on the field representing the resource, as mandated in AEP-133.

Details

This rule looks at any message matching Create*Request and complains if the resource field does not have a google.api.field_behavior annotation with a value of REQUIRED.

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "library.googleapis.com/Publisher"
  ];
  Book book = 2;  // Should also have (google.api.field_behavior) = REQUIRED.
}

Correct code for this rule:

// Correct.
message CreateBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "library.googleapis.com/Publisher"
  ];
  Book book = 2 [(google.api.field_behavior) = REQUIRED];
}

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 CreateBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "library.googleapis.com/Publisher"
  ];

  // (-- api-linter: core::0133::request-resource-behavior=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  Book book = 2;
}

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

Create methods- Resource field

Create methods: Resource field

This rule enforces that all Create standard methods have a field in the request message for the resource itself, as mandated in AEP-133.

Details

This rule looks at any message matching Create*Request and complains if there is no field of the resource’s type with the expected field name.

Examples

Incorrect code for this rule:

// Incorrect.
// `Book book` is missing.
message CreateBookRequest {
  string publisher = 1;
  string book_id = 3;
}

// Incorrect.
message CreateBookRequest {
  bytes parent = 1;
  Book payload = 2;  // Field name should be `book`.
  string book_id = 3;
}

Correct code for this rule:

// Correct.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string book_id = 3;
}

Disabling

If you need to violate this rule, use a leading comment above the message (if the resource field is missing) or above the field (if it is improperly named). Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0133::request-resource-field=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message CreateBookRequest {
  string publisher = 1;
  Book payload = 2;
  string book_id = 3;
}

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

Create methods- Unknown fields

Create methods: Unknown fields

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

Details

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

• string parent (AEP-133)
• {Resource} {resource} (AEP-133)
• string {resource}_id (AEP-133)
• string request_id (AEP-155)

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string book_id = 3;
  string library_id = 4;  // Non-standard field.
}

Correct code for this rule:

// Correct.
message CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string id = 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 CreateBookRequest {
  string parent = 1;
  Book book = 2;
  string id = 3;

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

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

Create methods- Parent field resource reference

Create methods: Parent field resource reference

This rule enforces that all Create standard methods with a string parent field use a proper google.api.resource_reference, that being either a child_type referring to the created resource or a type referring directly to the parent resource, as mandated in AEP-133.

Details

This rule looks at any message matching Create*Request and complains if the google.api.resource_reference on the parent field refers to the wrong resource.

Examples

Incorrect code for this rule:

// Incorrect.
message CreateBooksRequest {
  // `child_type` should be used instead of `type` when referring to the
  // created resource on a parent field.
  string parent = 1 [(google.api.resource_reference).type = "library.googleapis.com/Book"];
  Book book = 2;
}

Correct code for this rule:

// Correct.
message CreateBooksRequest {
  string parent = 1 [(google.api.resource_reference).child_type = "library.googleapis.com/Book"];
  Book book = 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 CreateBooksRequest {
  // (-- api-linter: core::0133::resource-reference-type=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string parent = 1 [(google.api.resource_reference).type = "library.googleapis.com/Book"];
  Book book = 2;
}

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

Create methods- Resource response message

Create methods: Resource response message

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

Details

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

It also permits a response of google.longrunning.Operation; in this case, it checks the response_type in the google.longrunning.operation_info annotation and ensures that it corresponds to the name of the RPC with the prefix Create removed.

Examples

Standard

Incorrect code for this rule:

// Incorrect.
// Should be `Book`.
rpc CreateBook(CreateBookRequest) returns (CreateBookResponse) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*}/books"
    body: "book"
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*}/books"
    body: "book"
  };
}

Long-running operation

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{book.name=publishers/*}/books"
    body: "book"
  };
  option (google.longrunning.operation_info) = {
    response_type: "CreateBookResponse"  // Should be "Book".
    metadata_type: "CreateBookMetadata"
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{book.name=publishers/*}/books"
    body: "book"
  };
  option (google.longrunning.operation_info) = {
    response_type: "Book"
    metadata_type: "CreateBookMetadata"
  };
}

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::0133::response-message-name=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc CreateBook(CreateBookRequest) returns (CreateBookResponse) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*}/books"
    body: "book"
  };
}

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

Create methods- Synonym check

Create methods: Synonym check

This rule enforces that single-resource creation methods have names beginning with Create, as mandated in AEP-133.

Details

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

• Insert
• Make
• Post

Examples

Incorrect code for this rule:

// Incorrect.
rpc InsertBook(InsertBookRequest) returns (Book) {  // Should be `CreateBook`.
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

Correct code for this rule:

// Correct.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

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::0133::synonyms=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc InsertBook(InsertBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
}

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