rpc-request-standard-name

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

This rule checks whether the request type of every RPC is named after the RPC, for example GetPetRequest for the RPC GetPet.

Rule details

When every RPC has its own request message, fields can be added to the request of one RPC without changing the others. Naming the message after the RPC makes this one-to-one relation visible.

The rpc-request-standard-name rule accepts two names for the request type of the RPC <rpc> in the service <service>: <rpc>Request and <service><rpc>Request. Only the last component of the type name is compared, so acme.pets.v1.GetPetRequest is accepted as well. For any other request type, the rule reports:

Request type of RPC '<rpc>' should be named '<rpc>Request' or '<service><rpc>Request', not '<type>'

where <type> is the type name as written in the RPC.

To recognize google.protobuf.Empty, the rule resolves the request types among the declarations of the file and of the files it imports; google/protobuf/empty.proto is known built in. A type that cannot be resolved is compared as written, without a leading dot.

Turn the rule off if the RPCs are part of an existing API that you cannot change. To allow a single RPC, add an // apigenie-lint-disable rpc-request-standard-name comment to it.

Configuration

The configuration block is an object with boolean properties:

  • allow_google_protobuf_empty_requests: whether google.protobuf.Empty is accepted as a request type (default false). The type is resolved, so .google.protobuf.Empty is recognized, too.
  • allow_google_protobuf_empty_responses: accepted for symmetry with the related rules, but ignored by this rule.

Configuration example

version: "1.0"
commands:
  lint:
    protobuf:
      rules:
        rpc-request-standard-name:
          - warning
          - allow_google_protobuf_empty_requests: true

Examples

Good. With the default configuration.

syntax = "proto3";

package acme.pets.v1;

service PetService {
  rpc GetPet(GetPetRequest) returns (GetPetResponse);
  rpc ListPets(PetServiceListPetsRequest) returns (ListPetsResponse);
}

message GetPetRequest {
  string name = 1;
}

message GetPetResponse {
  string name = 1;
}

message PetServiceListPetsRequest {
  int32 page_size = 1;
}

message ListPetsResponse {
  repeated string names = 1;
}

Bad. With the default configuration, the linter reports Request type of RPC 'GetPet' should be named 'GetPetRequest' or 'PetServiceGetPetRequest', not 'PetId'.

syntax = "proto3";

package acme.pets.v1;

service PetService {
  rpc GetPet(PetId) returns (GetPetResponse);
}

message PetId {
  string name = 1;
}

message GetPetResponse {
  string name = 1;
}

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.protobuf has the details.

commands:
  lint:
    protobuf:
      rules:
        rpc-request-standard-name: off

Related rules

Was this helpful?