search

microsoft / api-guidelines

Microsoft REST API Guidelines
Other
22.69k stars 2.71k forks source link

Update pagination guidance to clarify the difference between server-side and client-side paging #486

Closed corranrogue9 closed 1 year ago

corranrogue9 commented 1 year ago

I noticed that we have been considering the use of @nextLink to be synonymous with server-driven paging. There are some workloads that provide a @nextLink using the $skip and $top query parameters. These workloads are "really" using client-driven paging since they make no guarantee that elements aren't missing or duplicated. I added a section to call out that services must use some form of pagination, and that they can use either server-driven, client-driven, or both. I also note that server-driven paging leverages the $skiptoken query paramter.

OlgaPodo commented 1 year ago

I concur with these changes as an interim clarification step even though we will need to merge REST guidelines to Graph guidelines later this year. @dkershaw10 could you please review as well?

OlgaPodo commented 1 year ago

@corranrogue9 Could you please add an additional guidance to cover https://github.com/microsoft/api-guidelines/issues/467 as it directly relates to paging?

OlgaPodo commented 1 year ago

as per discussion decided to resolve issue #467 as a separate work.

corranrogue9 commented 1 year ago

@dkershaw10 or @OlgaPodo do you have additional feedback on this change?