From 88831b052375fa31876ade4a9bc09effdddc6295 Mon Sep 17 00:00:00 2001
From: Stephen J Day <stephen.day@docker.com>
Date: Wed, 22 Jul 2015 20:00:28 -0700
Subject: [PATCH] Clean up pagination specification

Some missing descriptions and error code for tags pagination was cleaned up to
ensure clarity. Specifically, we ensure the request variations are named and
the proper error codes are included.

Signed-off-by: Stephen J Day <stephen.day@docker.com>
---
 docs/spec/api.md               | 69 ++++++++++++++++++++++++++++++++--
 registry/api/v2/descriptors.go | 27 +++++++++++++
 2 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/docs/spec/api.md b/docs/spec/api.md
index a3606d8db..68c3f0010 100644
--- a/docs/spec/api.md
+++ b/docs/spec/api.md
@@ -1123,6 +1123,7 @@ Retrieve information about tags.
 Fetch the tags under the repository identified by `name`.
 
 
+##### Tags
 
 ```
 GET /v2/<name>/tags/list
@@ -1130,7 +1131,7 @@ Host: <registry host>
 Authorization: <scheme> <token>
 ```
 
-
+Return all tags for the repository
 
 
 The following parameters should be specified on the request:
@@ -1149,7 +1150,6 @@ The following parameters should be specified on the request:
 ```
 200 OK
 Content-Length: <length>
-Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
@@ -1232,6 +1232,7 @@ The error codes that may be included in the response body are enumerated below:
 
 
 
+##### Tags Paginated
 
 ```
 GET /v2/<name>/tags/list?n=<integer>last=<integer>
@@ -1256,6 +1257,7 @@ The following parameters should be specified on the request:
 ```
 200 OK
 Content-Length: <length>
+Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
@@ -1279,6 +1281,67 @@ The following headers will be returned with the response:
 
 
 
+###### On Failure: Not Found
+
+```
+404 Not Found
+Content-Type: application/json; charset=utf-8
+
+{
+	"errors:" [
+	    {
+            "code": <error code>,
+            "message": "<error message>",
+            "detail": ...
+        },
+        ...
+    ]
+}
+```
+
+The repository is not known to the registry.
+
+
+
+The error codes that may be included in the response body are enumerated below:
+
+|Code|Message|Description|
+|----|-------|-----------|
+| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
+
+
+
+###### On Failure: Unauthorized
+
+```
+401 Unauthorized
+Content-Type: application/json; charset=utf-8
+
+{
+	"errors:" [
+	    {
+            "code": <error code>,
+            "message": "<error message>",
+            "detail": ...
+        },
+        ...
+    ]
+}
+```
+
+The client does not have access to the repository.
+
+
+
+The error codes that may be included in the response body are enumerated below:
+
+|Code|Message|Description|
+|----|-------|-----------|
+| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. |
+
+
+
+
 
 ### Manifest
 
@@ -3157,7 +3220,6 @@ Request an unabridged list of repositories available.
 ```
 200 OK
 Content-Length: <length>
-Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
@@ -3202,6 +3264,7 @@ The following parameters should be specified on the request:
 ```
 200 OK
 Content-Length: <length>
+Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
diff --git a/registry/api/v2/descriptors.go b/registry/api/v2/descriptors.go
index ee895b722..635cb7f90 100644
--- a/registry/api/v2/descriptors.go
+++ b/registry/api/v2/descriptors.go
@@ -398,6 +398,8 @@ var routeDescriptors = []RouteDescriptor{
 				Description: "Fetch the tags under the repository identified by `name`.",
 				Requests: []RequestDescriptor{
 					{
+						Name:        "Tags",
+						Description: "Return all tags for the repository",
 						Headers: []ParameterDescriptor{
 							hostHeader,
 							authHeader,
@@ -455,6 +457,7 @@ var routeDescriptors = []RouteDescriptor{
 						},
 					},
 					{
+						Name:            "Tags Paginated",
 						Description:     "Return a portion of the tags for the specified repository.",
 						PathParameters:  []ParameterDescriptor{nameParameterDescriptor},
 						QueryParameters: paginationParameters,
@@ -483,6 +486,30 @@ var routeDescriptors = []RouteDescriptor{
 								},
 							},
 						},
+						Failures: []ResponseDescriptor{
+							{
+								StatusCode:  http.StatusNotFound,
+								Description: "The repository is not known to the registry.",
+								Body: BodyDescriptor{
+									ContentType: "application/json; charset=utf-8",
+									Format:      errorsBody,
+								},
+								ErrorCodes: []errcode.ErrorCode{
+									ErrorCodeNameUnknown,
+								},
+							},
+							{
+								StatusCode:  http.StatusUnauthorized,
+								Description: "The client does not have access to the repository.",
+								Body: BodyDescriptor{
+									ContentType: "application/json; charset=utf-8",
+									Format:      errorsBody,
+								},
+								ErrorCodes: []errcode.ErrorCode{
+									ErrorCodeUnauthorized,
+								},
+							},
+						},
 					},
 				},
 			},