From 0790a298ed04744b6d65d21f21c17a70cd67c02b Mon Sep 17 00:00:00 2001
From: Stephen J Day <stephen.day@docker.com>
Date: Tue, 2 Jun 2015 20:16:59 -0700
Subject: [PATCH] Paginate catalog and tag results with Link header

Move the specification to use a Link header, rather than a "next" entry in the
json results. This prevents requiring clients from parsing the request body to
issue the next request. It also ensures that the returned response body does
not change in between requests.

The ordering of the specification has been slightly tweaked, as well. Listing
image tags has been moved after the catalog specification. Tag pagination now
heavily references catalog pagination.

Signed-off-by: Stephen J Day <stephen.day@docker.com>
---
 docs/api/v2/descriptors.go | 26 +++++++++-----------------
 1 file changed, 9 insertions(+), 17 deletions(-)

diff --git a/docs/api/v2/descriptors.go b/docs/api/v2/descriptors.go
index 4eec6492..ee895b72 100644
--- a/docs/api/v2/descriptors.go
+++ b/docs/api/v2/descriptors.go
@@ -87,6 +87,13 @@ var (
 		Format:      "<digest>",
 	}
 
+	linkHeader = ParameterDescriptor{
+		Name:        "Link",
+		Type:        "link",
+		Description: "RFC5988 compliant rel='next' with URL to next result set, if available",
+		Format:      `<<url>?n=<last n value>&last=<last entry from response>>; rel="next"`,
+	}
+
 	paginationParameters = []ParameterDescriptor{
 		{
 			Name:        "n",
@@ -462,14 +469,7 @@ var routeDescriptors = []RouteDescriptor{
 										Description: "Length of the JSON response body.",
 										Format:      "<length>",
 									},
-								},
-								Fields: []ParameterDescriptor{
-									{
-										Name:        "next",
-										Type:        "url",
-										Description: "Provides the URL to get the next set of results, if available.",
-										Format:      "<url>",
-									},
+									linkHeader,
 								},
 								Body: BodyDescriptor{
 									ContentType: "application/json; charset=utf-8",
@@ -479,7 +479,6 @@ var routeDescriptors = []RouteDescriptor{
         <tag>,
         ...
     ],
-    "next": "<url>?last=<name>&n=<last value of n>"
 }`,
 								},
 							},
@@ -1439,14 +1438,7 @@ var routeDescriptors = []RouteDescriptor{
 										Description: "Length of the JSON response body.",
 										Format:      "<length>",
 									},
-								},
-								Fields: []ParameterDescriptor{
-									{
-										Name:        "next",
-										Type:        "url",
-										Description: "Provides the URL to get the next set of results, if available.",
-										Format:      "<url>",
-									},
+									linkHeader,
 								},
 							},
 						},