rpc-response-standard-name
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether the response type of every RPC is named after the RPC, for example
GetPetResponse for the RPC GetPet.
Rule details
When every RPC has its own response message, fields can be added to the response of one RPC
without changing the others: returning a bare Pet from GetPet leaves no room for metadata
that only this RPC needs. Naming the message after the RPC makes this one-to-one relation
visible.
The rpc-response-standard-name rule accepts two names for the response type of the RPC <rpc>
in the service <service>: <rpc>Response and <service><rpc>Response. Only the last component
of the type name is compared, so acme.pets.v1.GetPetResponse is accepted as well. For any other
response type, the rule reports:
Response type of RPC '<rpc>' should be named '<rpc>Response' or '<service><rpc>Response', not '<type>'
where <type> is the type name as written in the RPC.
To recognize google.protobuf.Empty, the rule resolves the response 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-response-standard-name comment to it.
Configuration
The configuration block is an object with boolean properties:
allow_google_protobuf_empty_responses: whethergoogle.protobuf.Emptyis accepted as a response type (defaultfalse). The type is resolved, so.google.protobuf.Emptyis recognized, too.allow_google_protobuf_empty_requests: accepted for symmetry with the related rules, but ignored by this rule.
Configuration example
version: "1.0"
commands:
lint:
protobuf:
rules:
rpc-response-standard-name:
- warning
- allow_google_protobuf_empty_responses: true
Examples
Good. With the default configuration.
syntax = "proto3";
package acme.pets.v1;
service PetService {
rpc GetPet(GetPetRequest) returns (GetPetResponse);
rpc ListPets(ListPetsRequest) returns (PetServiceListPetsResponse);
}
message GetPetRequest {
string name = 1;
}
message GetPetResponse {
string name = 1;
}
message ListPetsRequest {
int32 page_size = 1;
}
message PetServiceListPetsResponse {
repeated string names = 1;
}
Good. With allow_google_protobuf_empty_responses: true.
syntax = "proto3";
package acme.pets.v1;
import "google/protobuf/empty.proto";
service PetService {
rpc DeletePet(DeletePetRequest) returns (google.protobuf.Empty);
}
message DeletePetRequest {
string name = 1;
}
Bad. With the default configuration, the linter reports
Response type of RPC 'GetPet' should be named 'GetPetResponse' or 'PetServiceGetPetResponse', not 'Pet'.
syntax = "proto3";
package acme.pets.v1;
service PetService {
rpc GetPet(GetPetRequest) returns (Pet);
}
message GetPetRequest {
string name = 1;
}
message Pet {
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-response-standard-name: off