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

@@ -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>",
 									},
-								},
+									linkHeader,
-								Fields: []ParameterDescriptor{
-									{
-										Name:        "next",
-										Type:        "url",
-										Description: "Provides the URL to get the next set of results, if available.",
-										Format:      "<url>",
-									},
 								},
 								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>",
 									},
-								},
+									linkHeader,
-								Fields: []ParameterDescriptor{
-									{
-										Name:        "next",
-										Type:        "url",
-										Description: "Provides the URL to get the next set of results, if available.",
-										Format:      "<url>",
-									},
 								},
 							},
 						},