From 4b569b5e4d74b49b777927d9410d09a43ebf5947 Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Mon, 8 Jan 2018 15:48:38 -0600 Subject: [PATCH] Expand note about rfc5988 link header An alternate that is suggested for people who cannot add link sections to the response body is the RFC 5988 Link header. Move it to its own section for ease of linking, and change the text from 'can consider' to 'should'. Also, add a note about API breakage and versioning related to adding Link headers. Change-Id: Ide4124513e3328084c53a2122384a4e25ea6c863 --- guidelines/pagination_filter_sort.rst | 28 +++++++++++++++++++++++---- 1 file 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 Request** response should be returned, with a clear explanation in the error message that the requested marker value does not exist. +Pagination Links +~~~~~~~~~~~~~~~~ + It is also helpful to users if services generate pagination links and include them in the :ref:`links` portion of the response body. Providing the following link types will make pagination navigation easier: @@ -127,10 +130,6 @@ Would look more akin to:: ] } -Alternatively, if services are not including JSON `Hyper-Schema`_ links in -their responses they can consider using the ``Link`` header as defined in -:rfc:`5988` and :rfc:`6903`. - When using links, the links that are included change based on which page the user requested. For example, if the user has requested the first page, then it still 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. In many cases, such link calculation would require querying the entire dataset. Therefore implementing the ``last`` link is optional. +Link Header Alternative +~~~~~~~~~~~~~~~~~~~~~~~ + +If services are not including JSON `Hyper-Schema`_ links in their responses, +or if they cannot include them for some reasons, they should return pagination +links in the ``Link`` header as defined in :rfc:`5988` and :rfc:`6903`. + +.. note:: + + Adding the ``Link`` to responses should not be considered an API contract + change that needs a either a minor version bump or a microversion. Because + of the nature of HTTP headers and the relationship of REST services with + proxies, load balancers and API gateways, HTTP clients must already handle + the existence of additional headers that may not be relevant. + + Consuming pagination is a fundamental operation that is frequently not done + on a per-service basis. Requiring a user to undergo a microversion + negotiation or minor version is extra per-service work that is both difficult + and which carries no value. Users can simply check to see if a Link header + exists, and if one does, they can consume the data in it. + Filtering ---------