AEP-0122 Linter Rules

HTTP URI case

This rule enforces that the HTTP URI pattern only uses kebab-case for word separation, as mandated in AEP-122.

Details

This rule scans all methods and ensures that the _ character and no uppercase letters are present.

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetElectronicBook(GetElectronicBookRequest) returns (ElectronicBook) {
  option (google.api.http) = {
    // Should be "electronicBooks", not "electronnamethic_books".
    get: "/v1/{path=publishers/*/electronicBooks/*}"
  };
}

Correct code for this rule:

// Correct.
rpc GetElectronicBook(GetElectronicBookRequest) returns (ElectronicBook) {
  option (google.api.http) = {
    get: "/v1/{path=publishers/*/electronic-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::0122::camel-case-uris=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetElectronicBook(GetElectronicBookRequest) returns (ElectronicBook) {
  option (google.api.http) = {
    // Should be "electronic-books", not "electronic_books".
    get: "/v1/{path=publishers/*/electronic_books/*}"
  };
}

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

No self links

This rule enforces that resource messages do not contain any fields called string self_link, as mandated in AEP-122.

Details

This rule complains if it sees a resource field of type string that is also named self_link.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };
  string path = 1;

  // Incorrect. Resources should contain self-links.
  string self_link = 2;
}

Correct code for this rule:

// Correct.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };
  string path = 1;
}

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.

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };
  string path = 1;

  // (-- api-linter: core::0122::no-self-links=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string self_link = 2;
}

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

Path field suffix

This rule enforces that fields do not use the suffix _path, as mandated in AEP-122.

Details

This rule scans all fields complains if it sees the suffix _path on a field.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string path = 1;
  string author_path = 2;  // Should be `author`.
}

Correct code for this rule:

// Correct.
message Book {
  string path = 1;
  string author = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the method.

// (-- api-linter: core::0122::path-suffix=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string path = 1;
  string author_path = 2;  // Should be `author`.
}

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

Resource pattern collection identifiers

This rule enforces that messages that have a google.api.resource annotation have properly formatted collection identifiers in each pattern, as described in AEP-122.

Details

This rule scans messages with a google.api.resource annotation, and validates the format of pattern collection identifiers, specifically that they are in lowerCamelCase form and must start with a lowercase letter.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    // Collection identifiers must be kebab-case.
    pattern: "Publishers/{publisher}/publishedBooks/{book}"
  };
  string path = 1;
}

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    // Collection identifiers must begin with a lower-cased letter.
    pattern: "/publishers/{publisher}/Published-books/{book}"
  };
  string path = 1;
}

Correct code for this rule:

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

Disabling

If you need to violate this rule, use a leading comment above the message.

// (-- api-linter: core::0122::resource-collection-identifiers=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "Publishers/{publisher}/Books/{book}"
  };
  string path = 1;
}

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

Output Only Resource ID fields

This rule enforces that resource ID fields are classified as OUTPUT_ONLY, as mandated in AEP-122.

Details

This rule scans all resource fields and complains if it sees an ID field, named as uid or with the _id suffix, that is not classified as OUTPUT_ONLY.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };
  string path = 1;
  // Should have `(google.api.field_behavior) = OUTPUT_ONLY`.
  string book_id = 2;
  // Should have `(google.api.field_behavior) = OUTPUT_ONLY`.
  string uid = 3;
}

Correct code for this rule:

// Correct.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };
  string path = 1;
  string book_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  string uid = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

Disabling

If you need to violate this rule, use a leading comment above the field.

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "books/{book}"
  };
  string path = 1;
  // (-- api-linter: core::0122::resource-id-output-only=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string book_id = 2;
  // (-- api-linter: core::0122::resource-id-output-only=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string uid = 3;
}

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

Resource reference type

This rule enforces that all fields with the google.api.resource_reference annotation are strings, as mandated in AEP-122.

Details

This rule complains if it sees a field with a google.api.resource_reference that has a type other than string.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string path = 1;

  // Resource references should be strings.
  Author author = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Author"
  }];
}

Correct code for this rule:

// Correct.
message Book {
  string path = 1;

  string author = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Author"
  }];
}

// Correct.
message Book {
  string path = 1;

  // If "author" is not a first-class resource, then it may be a composite
  // field within the book.
  Author author = 2;
}

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.

message Book {
  string path = 1;

  // (-- api-linter: core::0122::resource-reference-type=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  Author author = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Author"
  }];
}

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