From b429176dd7191dbfe9f47bbf7fce75fca441fbc5 Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Fri, 6 Feb 2015 17:49:50 -0800 Subject: [PATCH] Move API specification into correct position The goal is to maintain a specification heirarchy under doc/spec. This change sets the example. The Makefile has also been changed update the AUTHORS file and can now generate the specification. Signed-off-by: Stephen J Day --- AUTHORS | 1 + Makefile | 12 +++++++--- cmd/registry-api-descriptor-template/main.go | 2 +- doc/{SPEC.md => spec/api.md} | 24 ++++++++++---------- doc/{SPEC.md.tmpl => spec/api.md.tmpl} | 0 5 files changed, 23 insertions(+), 16 deletions(-) rename doc/{SPEC.md => spec/api.md} (97%) rename doc/{SPEC.md.tmpl => spec/api.md.tmpl} (100%) diff --git a/AUTHORS b/AUTHORS index 007d001a..a6b19ea6 100644 --- a/AUTHORS +++ b/AUTHORS @@ -3,6 +3,7 @@ Andrey Kostov Anton Tiurin Arnaud Porterie Brian Bland +Derek McGowan Josh Hawn Olivier Gambier Stephen J Day diff --git a/Makefile b/Makefile index b02c02a0..a034a312 100644 --- a/Makefile +++ b/Makefile @@ -6,10 +6,10 @@ GO_LDFLAGS=-ldflags "-X `go list ./version`.Version `git describe --match 'v[0-9 .PHONY: clean all fmt vet lint build test binaries .DEFAULT: default -all: clean fmt vet fmt lint build test binaries +all: AUTHORS clean fmt vet fmt lint build test binaries AUTHORS: .mailmap .git/ORIG_HEAD .git/FETCH_HEAD .git/HEAD - git log --format='%aN <%aE>' | sort -fu >> $@ + git log --format='%aN <%aE>' | sort -fu > $@ # This only needs to be generated by hand when cutting full releases. version/version.go: @@ -18,6 +18,12 @@ version/version.go: ${PREFIX}/bin/registry: version/version.go $(shell find . -type f -name '*.go') go build -o $@ ${GO_LDFLAGS} ./cmd/registry +${PREFIX}/bin/registry-api-descriptor-template: version/version.go $(shell find . -type f -name '*.go') + go build -o $@ ${GO_LDFLAGS} ./cmd/registry-api-descriptor-template + +doc/spec/api.md: doc/spec/api.md.tmpl ${PREFIX}/bin/registry-api-descriptor-template + ./bin/registry-api-descriptor-template $< > $@ + vet: go vet ./... @@ -37,7 +43,7 @@ test: test-full: go test ./... -binaries: ${PREFIX}/bin/registry +binaries: ${PREFIX}/bin/registry ${PREFIX}/bin/registry-api-descriptor-template clean: rm -rf "${PREFIX}/bin/registry" diff --git a/cmd/registry-api-descriptor-template/main.go b/cmd/registry-api-descriptor-template/main.go index 5e2e71d7..f6f20925 100644 --- a/cmd/registry-api-descriptor-template/main.go +++ b/cmd/registry-api-descriptor-template/main.go @@ -4,7 +4,7 @@ // For example, to generate a new API specification, one would execute the // following command from the repo root: // -// $ registry-api-descriptor-template doc/SPEC.md.tmpl > doc/SPEC.md +// $ registry-api-descriptor-template doc/spec/api.md.tmpl > doc/spec/api.md // // The templates are passed in the api/v2.APIDescriptor object. Please see the // package documentation for fields available on that object. The template diff --git a/doc/SPEC.md b/doc/spec/api.md similarity index 97% rename from doc/SPEC.md rename to doc/spec/api.md index 3fc3e372..5d22ff97 100644 --- a/doc/SPEC.md +++ b/doc/spec/api.md @@ -693,7 +693,7 @@ The error codes encountered via the API are enumerated in the following table: `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. `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. `SIZE_INVALID` | provided length did not match content length | When a layer is uploaded, the provided size will be checked against the uploaded content. If they do not match, this error will be returned. - `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. + `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. `MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository. @@ -1004,7 +1004,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. | @@ -1159,7 +1159,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. | | `MANIFEST_INVALID` | manifest invalid | During upload, manifests undergo several checks ensuring validity. If those checks fail, this error may be returned, unless a more specific error is included. The detail will contain information the failed validation. | | `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. | @@ -1333,7 +1333,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. | @@ -1506,7 +1506,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | @@ -1655,7 +1655,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | @@ -1816,7 +1816,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | @@ -1920,7 +1920,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | @@ -2045,7 +2045,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | @@ -2203,7 +2203,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | @@ -2372,7 +2372,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | @@ -2539,7 +2539,7 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| -------|----|------|------------ -| `NAME_INVALID` | manifest name did not match URI | During a manifest upload, if the name in the manifest does not match the uri name, this error will be returned. | +| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | diff --git a/doc/SPEC.md.tmpl b/doc/spec/api.md.tmpl similarity index 100% rename from doc/SPEC.md.tmpl rename to doc/spec/api.md.tmpl