How to list things: API name convention / request types for gRPC

Viewed 13

I read the standard methods in the API design guide by google, and wonder about listing things, ref https://cloud.google.com/apis/design/standard_methods#list

The example is listing books.

rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {}

This is nice and clean. And by adding some limitations in the ListBooksReuest we can add some modifications to listing ALL books, by some paginations/offset etc.

But my world often isn't this clean. There are many ways to list things, different ways of grouping and sorting.

Eg. I'm tempted to make a rpc ListBooksByAuthor that takes an author_id as request (or perhaps first_name/last_name as strings). Or a rpc ListBooksByCoverColor, or rpc ListBooksByCountyOfAuthorsBirthplace, or ...

Should multiple such List-ings coexist in the API? Is that considered correct?

Or should I make more elaborate ListBooksRequest that would allow for multiple ways of listing, like:

message ListBooksRequest {

  bool list_all_books = 1;

  bool list_by_author_id = 2;
  int64 author_id = 3;

  bool list_by_cover_color = 4;
  string cover_color = 5;
}

And then make the backend service decide what and how to list (e.g by first True bool param in message). This feels ugly.

I have not found any answer to this in the API design guide.

What do you consider the nice way to offer more than one way to list out datapoints?

PS: Do I have other options than 1) many similar rpc ListStuffByConditions(req) returns (resp) and 2) bake preferences into ListBooksRequest message that goes into a cleaner sounding rpc ListBooks?

0 Answers
Related