AEP-0127 Linter Rules

HTTP URI case

This rule enforces that the HTTP annotation is present on all non-bidi-streaming methods and absent on streaming methods, as mandated in AEP-127.

Details

This rule scans all methods that a google.api.http annotation is present on all non-streaming methods, as well as methods that only use streaming in one direction. It complains if an annotation is not found.

For bidi-streaming methods, it complains if a google.api.http annotation is found.

Examples

Unary methods

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book);  // Missing `google.api.http`.

Correct code for this rule:

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

Bidi-streaming methods

Incorrect code for this rule:

// Incorrect.
rpc EditBook(stream EditBookRequest) returns (stream EditBookResponse) {
  option (google.api.http) = {  // HTTP/1.1 not supported for bi-di streaming.
    post: "/v1/{path=publishers/*/books/*}:edit"
    body: "*"
  };
}

Correct code for this rule:

// Correct.
rpc EditBook(stream EditBookRequest) returns (stream EditBookResponse);

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::0127::http-annotation=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.

HTTP Pattern Variables

This rule enforces that any HTTP annotations that reference a resource must match one of the pattern strings defined by that resource, as mandated in AEP-127.

Details

This rule ensures that google.api.http path template variables that represent a resource path match one of the resource path patterns of the resource that the field being referenced represents.

Examples

Incorrect code for this rule:

// Incorrect.
// The template for the `path` variable in the `google.api.http` annotation
// is missing segments from the Book message's `pattern`.
rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
        get: "v1/{path=shelves/*}"
    };
}
message GetBookRequest {
    string path = 1 [
        (google.api.resource_reference).type = "library.googleapis.com/Book"
    ];
}
message Book {
    option (google.api.resource) = {
        type: "library.googleapis.com/Book"
        pattern: "shelves/{shelf}/books/{book}"
    };

    // Book resource path.
    string path = 1;
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
        get: "v1/{path=shelves/*/books/*}"
    };
}
message GetBookRequest {
    string path = 1 [
        (google.api.resource_reference).type = "library.googleapis.com/Book"
    ];
}
message Book {
    option (google.api.resource) = {
        type: "library.googleapis.com/Book"
        pattern: "shelves/{shelf}/books/{book}"
    };

    // Book resource path.
    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.

// (-- api-linter: core::0127::http-template-pattern=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
        get: "v1/{path=shelves/*}"
    };
}

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

HTTP Pattern Variables

This rule enforces that HTTP annotation patterns follow the path template syntax rules, as mandated in AEP-127.

Details

This rule ensures that google.api.http patterns adhere to the following syntax rules.

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
        // Should start with a leading slash.
        get: "v1/{name=shelves/*}"
    };
}

Incorrect code for this rule:

// Incorrect.
rpc AddAuthor(AddAuthorRequest) returns (AddAuthorResponse) {
    option (google.api.http) = {
        // Verb should be marked off with the ':' character.
        post: "/v1/{book=publishers/*/books/*}-addAuthor"
        body: "*"
    };
}

Incorrect code for this rule:

// Incorrect.
rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    // The triple wildcard ('***') is not a part of the syntax.
    post: "/v1/{parent=publishers/***}"
    body: "book"
  };
}

Correct code for this rule:

// Correct.
rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
        get: "/v1/{name=shelves/*}"
    };
}

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::0127::http-template-syntax=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
        get: "v1/{name=shelves/*}"
    };
}

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

HTTP URI case

This rule enforces that HTTP annotations pull whole resource paths into variables, and not just the ID components, as mandated in AEP-127.

Details

This rule scans all methods and complains if it finds a URI with a variable whose value is *.

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
  // Should be /v1/{path=publishers/*/books/*}
  get: "/v1/publishers/{publisher_id}/books/{book_id}"
}

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
  // Should be /v1/{path=publishers/*/books/*}
  get: "/v1/publishers/{publisher_id=*}/books/{book_id=*}"
}

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::0127::resource-path-extraction=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
rpc GetBook(GetBookRequest) returns (Book) {
  get: "/v1/publishers/{publisher_id}/books/{book_id}"
}

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

URI Forward Slashes

This rule enforces that URIs must begin with a forward slash, as mandated in AEP-127.

Details

This rule scans all methods and complains if it finds a URI that does not start with /.

Examples

Incorrect code for this rule:

// Incorrect.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    // Should be /v1/{path=publishers/*/books/*}
    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

Do not violate this rule. This would create an invalid URL.