Returning multiple items in gRPC: repeated List or stream single objects?

user_5004822 0
Viewed 3140

gRPC newbie. I have a simple api:

Customer getCustomer(int id)
List<Customer> getCustomers()

So my proto looks like this:

message ListCustomersResponse {
  repeated Customer customer = 1;
}

rpc ListCustomers (google.protobuf.Empty) returns (ListCustomersResponse);
rpc GetCustomer (GetCustomerRequest) returns (Customer);

I was trying to follow Googles lead on the style. Originally I had returns (stream Customer) for GetCustomers, but Google seems to favor the ListxxxResponse style. When I generate the code, it ends up being:

public void getCustomers(com.google.protobuf.Empty request,
        StreamObserver<ListCustomersResponse> responseObserver) {

vs:

public void getCustomers(com.google.protobuf.Empty request,
        StreamObserver<Customer> responseObserver) {

Am I missing something? Why would I want to go through the hassle of creating a ListCustomersResponse when I can just do stream Customer and get the streaming functionality?

The ListCustomersResponse is just streaming the whole list at once vs streaming each customer. Googles preference seems to be to return the ListCustomersResponse style all of the time.

When is it appropriate to use the ListxxxResponse vs the stream response?

grpc-java grpc
1 Answers

This question is hard to answer without knowing what reference you're using. It's possible there's a miscommunication, or that the reference is simply wrong.

If you're looking at the gRPC Basics tutorial though, then I might have an inkling as to what caused a miscommunication. If that's indeed your reference, then it does not recommend returning repeated fields for streamed responses; your intuition is correct: you would just want to stream the singular Customer.

Here is what it says (screenshot intentional):

enter image description here

You might be reading rpc ListFeatures(Rectangle) as meaning an endpoint that returns a list [noun] of features. If so, that's a miscommunication. The guide actually means an endpoint to list [verb] features. It would have been less confusing if they just wrote rpc GetFeatures(Rectangle).

So, your proto should look more like this,

rpc GetCustomers (google.protobuf.Empty) returns (stream Customer);
rpc GetCustomer (GetCustomerRequest) returns (Customer);

generating exactly what you suspected made more sense.

Update

Ah I see, so you're looking at this example in googleapis:

  // Lists shelves. The order is unspecified but deterministic. Newly created
  // shelves will not necessarily be added to the end of this list.
  rpc ListShelves(ListShelvesRequest) returns (ListShelvesResponse) {
    option (google.api.http) = {
      get: "/v1/shelves"
    };
  }

...

// Response message for LibraryService.ListShelves.
message ListShelvesResponse {
  // The list of shelves.
  repeated Shelf shelves = 1;

  // A token to retrieve next page of results.
  // Pass this value in the
  // [ListShelvesRequest.page_token][google.example.library.v1.ListShelvesRequest.page_token]
  // field in the subsequent call to `ListShelves` method to retrieve the next
  // page of results.
  string next_page_token = 2;
}

Yeah, I think you've probably figured the same by now, but here they have chosen to use a simple RPC, as opposed to a server-side streaming RPC (see here). I emphasize this because, I think the important choice is not the stylistic difference between repeated versus stream, but rather the difference between a simple request-response API versus a more complex and less-ubiquitous streaming API.

In the googleapis example above, they're defining an API that returns a fixed and static number of items per page, e.g. 10 or 50. It would simply be overcomplicated to use streaming for this, when pagination is already so well-understood and prevalent in software architecture and REST APIs. I think that is what they should have said, rather than "a small number." So the complexity of streaming (and learning cost to you and future maintainers) has to justified, that's all. Suppose you're actually fetching thousands of (x, y, z) items for a Point Cloud or you're creating a live-updating bid-ask visualizer for some cryptocurrency, e.g.

enter image description here

Then you'd start asking yourself, "Is a simple request-response API my best option here?" So it just tends to be that, the larger the number of items needing to be returned, the more streaming APIs start to make sense. And that can be for conceptual reasons, e.g. the items are a live-updating stream in time like the above crypto example, or architectural, e.g. it would be more efficient to start displaying results in the UI as partial data streams back. I think the "small number" thing you read was an oversimplification.

user_9259130
Related