fcrozat/distribution
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up pagination specification

Browse Source 
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>
This commit is contained in:
Stephen J Day 2015-07-22 20:00:28 -07:00
parent 76f29c2630
commit 88831b0523
2 changed files with 93 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
docs/spec/api.md
View File

@ -1123,6 +1123,7 @@ Retrieve information about tags.
Fetch the tags under the repository identified by `name`. Fetch the tags under the repository identified by `name`.
##### Tags
``` ```
GET /v2/<name>/tags/list GET /v2/<name>/tags/list
@ -1130,7 +1131,7 @@ Host: <registry host>
Authorization: <scheme> <token> Authorization: <scheme> <token>
``` ```
Return all tags for the repository
The following parameters should be specified on the request: The following parameters should be specified on the request:
@ -1149,7 +1150,6 @@ The following parameters should be specified on the request:
``` ```
200 OK 200 OK
Content-Length: <length> Content-Length: <length>
Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
Content-Type: application/json; charset=utf-8 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> GET /v2/<name>/tags/list?n=<integer>last=<integer>
@ -1256,6 +1257,7 @@ The following parameters should be specified on the request:
``` ```
200 OK 200 OK
Content-Length: <length> Content-Length: <length>
Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
Content-Type: application/json; charset=utf-8 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 ### Manifest
@ -3157,7 +3220,6 @@ Request an unabridged list of repositories available.
``` ```
200 OK 200 OK
Content-Length: <length> Content-Length: <length>
Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
Content-Type: application/json; charset=utf-8 Content-Type: application/json; charset=utf-8
{ {
@ -3202,6 +3264,7 @@ The following parameters should be specified on the request:
``` ```
200 OK 200 OK
Content-Length: <length> Content-Length: <length>
Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
Content-Type: application/json; charset=utf-8 Content-Type: application/json; charset=utf-8
{ {

27
registry/api/v2/descriptors.go
View File

@ -398,6 +398,8 @@ var routeDescriptors = []RouteDescriptor{
Description: "Fetch the tags under the repository identified by `name`.", Description: "Fetch the tags under the repository identified by `name`.",
Requests: []RequestDescriptor{ Requests: []RequestDescriptor{
{ {
Name: "Tags",
Description: "Return all tags for the repository",
Headers: []ParameterDescriptor{ Headers: []ParameterDescriptor{
hostHeader, hostHeader,
authHeader, authHeader,
@ -455,6 +457,7 @@ var routeDescriptors = []RouteDescriptor{
}, },
}, },
{ {
Name: "Tags Paginated",
Description: "Return a portion of the tags for the specified repository.", Description: "Return a portion of the tags for the specified repository.",
PathParameters: []ParameterDescriptor{nameParameterDescriptor}, PathParameters: []ParameterDescriptor{nameParameterDescriptor},
QueryParameters: paginationParameters, 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,
},
},
},
}, },
}, },
}, },