Merge pull request #376 from mikekistler/pagination

Add guidance on including api-version in nextLink

Author: markweitzel

azure/ConsiderationsForServiceDesign.md

@@ -374,6 +374,40 @@ All responses should include the `x-ms-request-id` header with a unique id for t
 
 Finally, write sample code for your service's workflow and add the code you'd want customers using to gracefully recover from errors.  Is it actually graceful?  Is it something you'd be comfortable asking most customers to write?  We also highly encourage reaching out to customers during private preview and asking them for code they've written against your service.  Their error handling might match your expectations, you might find a strong need for better documentation, or you might find important opportunities to improve the errors you're returning.
 
+## Pagination
+
+Operations that return a collection of resources must consider pagination.
+There are hard limits to the payload size of HTTP responses, and when the size of a collection or the resources themselves
+can grow arbitrarily large there is the risk of exceeding this limit if the operation does not support pagination.
+Further, adding support for pagination is a breaking change so it should be supported in the initial GA of the service
+if there is any possibility that it will eventually be needed.
+
+There are two forms of pagination that MAY be supported by RESTful APIs.
+Server-driven paging mitigates against denial-of-service attacks by forcibly paginating a request over multiple response payloads.
+Client-driven paging enables clients to request only the number of resources that it can use at a given time.
+Services should almost always support server-driven paging and may optionally support client-driven paging.
+
+### Server-driven paging
+
+In server-driven paging, the service includes a `nextLink` property in the response to indicate that additional elements
+exist in the collection.
+The value of the `nextLink` property should be an opaque absolute URL that will return the next page of results.
+The absence of a `nextLink` property means that no additional pages are available.
+Since `nextLink` is an opaque URL it should include any query parameters required by the service, including `api-version`.
+The service should honor a request to a URL derived from `nextLink` by replacing the value for the `apl-version` query parameter
+with a different but valid api version. The service may reject the request if any other element of `nextLink` was modified.
+
+The service determines how many items to include in the response and may choose a different number for different collections and even for different pages of the same collection.
+An operation may allow the client to specify a maximum number of items in a response with an optional `maxpagesize` parameter.
+Operations that support `maxpagesize` should return no more than the value specified in `maxpagesize` but may return fewer.
+
+### Client-driven paging
+
+An operation may support `skip` and `top` query parameters to allow the client to specify an offset into the collection
+and the number of results to return, respectively.
+
+Note that when `top` specifies a value larger than the server-driven paging page size, the response will be paged accordingly.
+
 ## Getting Help: The Azure REST API Stewardship Board
 The Azure REST API Stewardship board is a collection of dedicated architects that are passionate about helping Azure service teams build interfaces that are intuitive, maintainable, consistent, and most importantly, delight our customers. Because APIs affect nearly all downstream decisions, you are encouraged to reach out to the Stewardship board early in the development process. These architects will work with you to apply these guidelines and identify any hidden pitfalls in your design.
 

azure/Guidelines.md

@@ -512,6 +512,8 @@ Note: To avoid potential collision of actions and resource ids, you should disal
 
 :white_check_mark: **DO** return a `nextLink` field with an absolute URL that the client can GET in order to retrieve the next page of the collection.
 
+:white_check_mark: **DO** include any query parameters required by the service in `nextLink`, including `api-version`.
+
 :ballot_box_with_check: **YOU SHOULD** use `value` as the name of the top-level array field unless a more appropriate name is available.
 
 :no_entry: **DO NOT** return the `nextLink` field at all when returning the last page of the collection.