From b084c77c70800143f49613cd8df2caf5d9e5c990 Mon Sep 17 00:00:00 2001 From: Patrick Devine Date: Wed, 2 Dec 2015 17:26:52 -0800 Subject: [PATCH] Clarify pagination for catalog API endpoint This change clarifies the way the catalog endpoint returns results when pagination was not explicitly requested. Signed-off-by: Patrick Devine --- docs/spec/api.md | 8 +++++++- docs/spec/api.md.tmpl | 10 ++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/spec/api.md b/docs/spec/api.md index 320d752fd..d6d2aad0c 100644 --- a/docs/spec/api.md +++ b/docs/spec/api.md @@ -822,7 +822,13 @@ the presence of a repository only guarantees that it is there but not that it is _not_ there. For registries with a large number of repositories, this response may be quite -large. If such a response is expected, one should use pagination. +large. If such a response is expected, one should use pagination. A registry +may also limit the amount of responses returned even if pagination was not +explicitly requested. In this case the `Link` header will be returned along +with the results, and subsequent results can be obtained by following the link +as if pagination had been initially requested. + +For details of the `Link` header, please see the _Pagination_ section. #### Pagination diff --git a/docs/spec/api.md.tmpl b/docs/spec/api.md.tmpl index 3f74d40a2..cfb019043 100644 --- a/docs/spec/api.md.tmpl +++ b/docs/spec/api.md.tmpl @@ -325,7 +325,7 @@ Above, we have bytestring `C` passed into a function, `SHA256`, that returns a bytestring `B`, which is the hash of `C`. `D` gets the algorithm concatenated with the hex encoding of `B`. We then define the identifier of `C` to `ID(C)` as equal to `D`. A digest can be verified by independently calculating `D` and -comparing it with identifier `ID(C)` +comparing it with identifier `ID(C)`. #### Digest Header @@ -822,7 +822,13 @@ the presence of a repository only guarantees that it is there but not that it is _not_ there. For registries with a large number of repositories, this response may be quite -large. If such a response is expected, one should use pagination. +large. If such a response is expected, one should use pagination. A registry +may also limit the amount of responses returned even if pagination was not +explicitly requested. In this case the `Link` header will be returned along +with the results, and subsequent results can be obtained by following the link +as if pagination had been initially requested. + +For details of the `Link` header, please see the _Pagination_ section. #### Pagination