summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--guidelines/pagination_filter_sort.rst28
1 files changed, 24 insertions, 4 deletions
diff --git a/guidelines/pagination_filter_sort.rst b/guidelines/pagination_filter_sort.rst
index 2c94247..6815861 100644
--- a/guidelines/pagination_filter_sort.rst
+++ b/guidelines/pagination_filter_sort.rst
@@ -66,6 +66,9 @@ determine what the next logical item would be. In those cases, a **400 Bad
66Request** response should be returned, with a clear explanation in the error 66Request** response should be returned, with a clear explanation in the error
67message that the requested marker value does not exist. 67message that the requested marker value does not exist.
68 68
69Pagination Links
70~~~~~~~~~~~~~~~~
71
69It is also helpful to users if services generate pagination links and include 72It is also helpful to users if services generate pagination links and include
70them in the :ref:`links` portion of the response body. Providing the following 73them in the :ref:`links` portion of the response body. Providing the following
71link types will make pagination navigation easier: 74link types will make pagination navigation easier:
@@ -127,10 +130,6 @@ Would look more akin to::
127 ] 130 ]
128 } 131 }
129 132
130Alternatively, if services are not including JSON `Hyper-Schema`_ links in
131their responses they can consider using the ``Link`` header as defined in
132:rfc:`5988` and :rfc:`6903`.
133
134When using links, the links that are included change based on which page the 133When using links, the links that are included change based on which page the
135user requested. For example, if the user has requested the first page, then it 134user requested. For example, if the user has requested the first page, then it
136still makes sense to include ``first``, ``self``, ``next``, and ``last`` but 135still makes sense to include ``first``, ``self``, ``next``, and ``last`` but
@@ -141,6 +140,27 @@ It should also be emphasized that calculating the ``last`` link can be costly.
141In many cases, such link calculation would require querying the entire dataset. 140In many cases, such link calculation would require querying the entire dataset.
142Therefore implementing the ``last`` link is optional. 141Therefore implementing the ``last`` link is optional.
143 142
143Link Header Alternative
144~~~~~~~~~~~~~~~~~~~~~~~
145
146If services are not including JSON `Hyper-Schema`_ links in their responses,
147or if they cannot include them for some reasons, they should return pagination
148links in the ``Link`` header as defined in :rfc:`5988` and :rfc:`6903`.
149
150.. note::
151
152 Adding the ``Link`` to responses should not be considered an API contract
153 change that needs a either a minor version bump or a microversion. Because
154 of the nature of HTTP headers and the relationship of REST services with
155 proxies, load balancers and API gateways, HTTP clients must already handle
156 the existence of additional headers that may not be relevant.
157
158 Consuming pagination is a fundamental operation that is frequently not done
159 on a per-service basis. Requiring a user to undergo a microversion
160 negotiation or minor version is extra per-service work that is both difficult
161 and which carries no value. Users can simply check to see if a Link header
162 exists, and if one does, they can consume the data in it.
163
144Filtering 164Filtering
145--------- 165---------
146 166