Change PaginationParams to make page_size and page_token mutually exclusive

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -2,9 +2,12 @@
 
 ## Summary
 
-This release adds a new component category `COMPONENT_CATEGORY_HVAC` to the API.
+Update of the `PaginationParams` struct.
 
-## New Features
+## Upgrading
+
+- `PaginationParams` has been changed so that the `page_size` and `page_token`
+  fields are now mutually exclusive.
 
 - A new component category `COMPONENT_CATEGORY_HVAC` has been added to the API
   to represent HVAC (Heating, Ventilation, and Air Conditioning) systems.

proto/frequenz/api/common/v1/pagination/pagination_params.proto

@@ -11,16 +11,21 @@ package frequenz.api.common.v1.pagination;
 
 // A message defining parameters for paginating list requests.
 // It can be appended to a request message to specify the desired page of
-// results and the maximum number of results per page. For initial requests
-// (requesting the first page), the page_token should not be provided. For
-// subsequent requests (requesting any page after the first), the
-// next_page_token from the previous responses PaginationInfo must be supplied.
-// The page_size should only be specified in the initial request and will be
-// disregarded in subsequent requests.
+// results and the maximum number of results per page.
 message PaginationParams {
-  // The maximum number of results to be returned per request.
-  optional uint32 page_size = 1;
+  oneof params {
+    // The maximum number of results to return in a single page. The service may
+    // return fewer results than requested. If unspecified, the service may
+    // choose a reasonable default.
+    // May only be specified in the first request.
+    uint32 page_size = 1;
 
-  // The token identifying a specific page of the list results.
-  optional string page_token = 2;
+    // A token identifying a page of results to return. This should be the value
+    // of the `next_page_token` field in the previous response's PaginationInfo.
+    // For the first request, this field should be omitted.
+    //
+    // To avoid keeping remembering the page_size across requests, service
+    // implementations may choose to encode the page_size in the page_token.
+    string page_token = 2;
+  }
 }