diff --git a/docs/content/spec/api.md b/docs/content/spec/api.md index 2bab67d36..0a4fa4b28 100644 --- a/docs/content/spec/api.md +++ b/docs/content/spec/api.md @@ -1146,14 +1146,13 @@ The error codes encountered via the API are enumerated in the following table: `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. - `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, or "n" is negative. + `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, "n" is negative or "n" is bigger than the maximum allowed. `RANGE_INVALID` | invalid content range | When a layer is uploaded, the provided range is checked against the uploaded chunk. This error is returned if the range is out of order. `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. `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. `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. - ### Base Base V2 API route. Typically, this can be used for lightweight version checks and to validate registry authentication. @@ -1226,6 +1225,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: Too Many Requests ```none @@ -1259,6 +1259,9 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + + ### Tags Retrieve information about tags. @@ -1266,7 +1269,6 @@ Retrieve information about tags. #### GET Tags Fetch the tags under the repository identified by `name`. - ##### Tags ```none @@ -1274,9 +1276,7 @@ GET /v2//tags/list Host: Authorization: ``` - Return all tags for the repository - The following parameters should be specified on the request: |Name|Kind|Description| @@ -1309,6 +1309,7 @@ The following headers will be returned with the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| + ###### On Failure: Authentication Required ```none @@ -1344,6 +1345,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -1377,6 +1379,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -1410,6 +1413,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -1443,20 +1447,20 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + ##### Tags Paginated ```none -GET /v2//tags/list?n=&last= +GET /v2//tags/list?n=&last= ``` - Return a portion of the tags for the specified repository. - The following parameters should be specified on the request: |Name|Kind|Description| |----|----|-----------| |`name`|path|Name of the target repository.| -|`n`|query|Limit the number of entries in each response. If not present, all entries will be returned.| +|`n`|query|Limit the number of entries in each response. It not present, 100 entries will be returned.| |`last`|query|Result set will include values lexically after last.| ###### On Success: OK @@ -1485,6 +1489,7 @@ The following headers will be returned with the response: |`Content-Length`|Length of the JSON response body.| |`Link`|RFC5988 compliant rel='next' with URL to next result set, if available| + ###### On Failure: Invalid pagination number ```none @@ -1509,7 +1514,8 @@ The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| -| `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, or "n" is negative. | +| `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, "n" is negative or "n" is bigger than the maximum allowed. | + ###### On Failure: Authentication Required @@ -1546,6 +1552,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -1579,6 +1586,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -1612,6 +1620,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -1645,6 +1654,9 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + + ### Manifest Create, update, delete and retrieve manifests. @@ -1697,6 +1709,7 @@ The following headers will be returned with the response: |----|-----------| |`Docker-Content-Digest`|Digest of the targeted content for the request.| + ###### On Failure: Bad Request ```none @@ -1724,6 +1737,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Authentication Required ```none @@ -1759,6 +1773,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -1792,6 +1807,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -1825,6 +1841,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -1858,6 +1875,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + #### PUT Manifest Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest. @@ -1910,6 +1928,7 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Content-Digest`|Digest of the targeted content for the request.| + ###### On Failure: Invalid Manifest ```none @@ -1940,6 +1959,7 @@ The error codes that may be included in the response body are enumerated below: | `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | + ###### On Failure: Authentication Required ```none @@ -1975,6 +1995,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -2008,6 +2029,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -2041,6 +2063,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -2074,6 +2097,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + ###### On Failure: Missing Layer(s) ```none @@ -2102,6 +2126,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | + ###### On Failure: Not allowed ```none @@ -2116,6 +2141,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | + #### DELETE Manifest Delete the manifest or tag identified by `name` and `reference` where `reference` can be a tag or digest. Note that a manifest can _only_ be deleted by digest. @@ -2141,6 +2167,8 @@ The following parameters should be specified on the request: 202 Accepted ``` + + ###### On Failure: Invalid Name or Reference ```none @@ -2168,6 +2196,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Authentication Required ```none @@ -2203,6 +2232,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -2236,6 +2266,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -2269,6 +2300,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -2302,6 +2334,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + ###### On Failure: Unknown Manifest ```none @@ -2329,6 +2362,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not allowed ```none @@ -2343,6 +2377,9 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | + + + ### Blob Operations on blobs identified by `name` and `digest`. Used to fetch or delete layers by digest. @@ -2350,7 +2387,6 @@ Operations on blobs identified by `name` and `digest`. Used to fetch or delete l #### GET Blob Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. - ##### Fetch Blob ```none @@ -2405,6 +2441,7 @@ The following headers will be returned with the response: |`Location`|The location where the layer should be accessible.| |`Docker-Content-Digest`|Digest of the targeted content for the request.| + ###### On Failure: Bad Request ```none @@ -2432,6 +2469,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not Found ```none @@ -2459,6 +2497,7 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | + ###### On Failure: Authentication Required ```none @@ -2494,6 +2533,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -2527,6 +2567,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -2560,6 +2601,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -2593,6 +2635,8 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + ##### Fetch Blob Part ```none @@ -2601,9 +2645,7 @@ Host: Authorization: Range: bytes=- ``` - This endpoint may also support RFC7233 compliant range requests. Support can be detected by issuing a HEAD request. If the header `Accept-Range: bytes` is returned, range requests can be used to fetch partial content. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -2634,6 +2676,7 @@ The following headers will be returned with the response: |`Content-Length`|The length of the requested blob chunk.| |`Content-Range`|Content range of blob chunk.| + ###### On Failure: Bad Request ```none @@ -2661,6 +2704,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not Found ```none @@ -2679,6 +2723,8 @@ Content-Type: application/json } ``` + + The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2686,6 +2732,7 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | + ###### On Failure: Requested Range Not Satisfiable ```none @@ -2729,6 +2776,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -2762,6 +2810,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -2795,6 +2844,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -2828,6 +2878,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + #### DELETE Blob Delete the blob identified by `name` and `digest` @@ -2855,6 +2906,8 @@ Content-Length: 0 Docker-Content-Digest: ``` + + The following headers will be returned with the response: |Name|Description| @@ -2862,12 +2915,15 @@ The following headers will be returned with the response: |`Content-Length`|0| |`Docker-Content-Digest`|Digest of the targeted content for the request.| + ###### On Failure: Invalid Name or Digest ```none 400 Bad Request ``` + + The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2875,6 +2931,7 @@ The error codes that may be included in the response body are enumerated below: | `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` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | + ###### On Failure: Not Found ```none @@ -2902,6 +2959,7 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | + ###### On Failure: Method Not Allowed ```none @@ -2928,6 +2986,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | + ###### On Failure: Authentication Required ```none @@ -2963,6 +3022,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -2996,6 +3056,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -3029,6 +3090,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -3062,6 +3124,9 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + + ### Initiate Blob Upload Initiate a blob upload. This endpoint can be used to create resumable uploads or monolithic uploads. @@ -3069,7 +3134,6 @@ Initiate a blob upload. This endpoint can be used to create resumable uploads or #### POST Initiate Blob Upload Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request. - ##### Initiate Monolithic Blob Upload ```none @@ -3081,9 +3145,7 @@ Content-Type: application/octet-stream ``` - Upload a blob identified by the `digest` parameter in single request. This upload will not be resumable unless a recoverable error is returned. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3113,12 +3175,15 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| + ###### On Failure: Invalid Name or Digest ```none 400 Bad Request ``` + + The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3126,6 +3191,7 @@ The error codes that may be included in the response body are enumerated below: | `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` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | + ###### On Failure: Not allowed ```none @@ -3140,6 +3206,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | + ###### On Failure: Authentication Required ```none @@ -3175,6 +3242,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -3208,6 +3276,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -3241,6 +3310,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -3274,6 +3344,8 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + ##### Initiate Resumable Blob Upload ```none @@ -3282,9 +3354,7 @@ Host: Authorization: Content-Length: 0 ``` - Initiate a resumable blob upload with an empty request body. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3315,12 +3385,15 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| + ###### On Failure: Invalid Name or Digest ```none 400 Bad Request ``` + + The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3328,6 +3401,7 @@ The error codes that may be included in the response body are enumerated below: | `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` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | + ###### On Failure: Authentication Required ```none @@ -3363,6 +3437,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -3396,6 +3471,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -3429,6 +3505,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -3462,6 +3539,8 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + ##### Mount Blob ```none @@ -3470,9 +3549,7 @@ Host: Authorization: Content-Length: 0 ``` - Mount a blob identified by the `mount` parameter from another repository. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3503,12 +3580,15 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| + ###### On Failure: Invalid Name or Digest ```none 400 Bad Request ``` + + The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3516,6 +3596,7 @@ The error codes that may be included in the response body are enumerated below: | `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` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | + ###### On Failure: Not allowed ```none @@ -3530,6 +3611,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | + ###### On Failure: Authentication Required ```none @@ -3565,6 +3647,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -3598,6 +3681,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -3631,6 +3715,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -3664,6 +3749,9 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + + ### Blob Upload Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests. The `Location` header and its parameters should be preserved by clients, using the latest value returned via upload related API calls. @@ -3677,9 +3765,7 @@ GET /v2//blobs/uploads/ Host: Authorization: ``` - Retrieve the progress of the current upload, as reported by the `Range` header. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3708,6 +3794,7 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| + ###### On Failure: Bad Request ```none @@ -3736,6 +3823,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not Found ```none @@ -3762,6 +3850,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + ###### On Failure: Authentication Required ```none @@ -3797,6 +3886,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -3830,6 +3920,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -3863,6 +3954,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -3896,10 +3988,10 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + #### PATCH Blob Upload Upload a chunk of data for the specified upload. - ##### Stream upload ```none @@ -3910,9 +4002,7 @@ Content-Type: application/octet-stream ``` - Upload a stream of data to upload without completing the upload. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3943,6 +4033,7 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| + ###### On Failure: Bad Request ```none @@ -3971,6 +4062,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not Found ```none @@ -3997,6 +4089,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + ###### On Failure: Authentication Required ```none @@ -4032,6 +4125,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -4065,6 +4159,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -4098,6 +4193,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -4131,6 +4227,8 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + ##### Chunked upload ```none @@ -4143,9 +4241,7 @@ Content-Type: application/octet-stream ``` - Upload a chunk of data to specified upload without completing the upload. The data will be uploaded to the specified Content Range. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4178,6 +4274,7 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| + ###### On Failure: Bad Request ```none @@ -4206,6 +4303,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not Found ```none @@ -4232,6 +4330,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + ###### On Failure: Requested Range Not Satisfiable ```none @@ -4275,6 +4374,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -4308,6 +4408,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -4341,6 +4442,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -4374,6 +4476,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + #### PUT Blob Upload Complete the upload specified by `uuid`, optionally appending the body as the final chunk. @@ -4387,9 +4490,7 @@ Content-Type: application/octet-stream ``` - Complete the upload, providing all the data in the body, if necessary. A request without a body will just complete the upload with previously uploaded content. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4422,6 +4523,7 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Content-Digest`|Digest of the targeted content for the request.| + ###### On Failure: Bad Request ```none @@ -4451,6 +4553,7 @@ The error codes that may be included in the response body are enumerated below: | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | + ###### On Failure: Not Found ```none @@ -4477,6 +4580,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + ###### On Failure: Authentication Required ```none @@ -4512,6 +4616,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -4545,6 +4650,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -4578,6 +4684,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -4611,6 +4718,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + #### DELETE Blob Upload Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. @@ -4621,9 +4729,7 @@ Host: Authorization: Content-Length: 0 ``` - Cancel the upload specified by `uuid`. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4649,6 +4755,7 @@ The following headers will be returned with the response: |----|-----------| |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| + ###### On Failure: Bad Request ```none @@ -4676,6 +4783,7 @@ The error codes that may be included in the response body are enumerated below: | `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. | + ###### On Failure: Not Found ```none @@ -4702,6 +4810,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | + ###### On Failure: Authentication Required ```none @@ -4737,6 +4846,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | + ###### On Failure: No Such Repository Error ```none @@ -4770,6 +4880,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `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: Access Denied ```none @@ -4803,6 +4914,7 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | + ###### On Failure: Too Many Requests ```none @@ -4836,6 +4948,9 @@ The error codes that may be included in the response body are enumerated below: |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | + + + ### Catalog List a set of available repositories in the local registry cluster. Does not provide any indication of what may be available upstream. Applications can only determine if a repository is available but not if it is not available. @@ -4843,15 +4958,12 @@ List a set of available repositories in the local registry cluster. Does not pro #### GET Catalog Retrieve a sorted, json list of repositories available in the registry. - ##### Catalog Fetch ```none GET /v2/_catalog ``` - Request an unabridged list of repositories available. The implementation may impose a maximum limit and return a partial set with pagination links. - ###### On Success: OK ```none @@ -4863,7 +4975,7 @@ Content-Type: application/json "repositories": [ , ... - ] + ], } ``` @@ -4875,14 +4987,14 @@ The following headers will be returned with the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| + + ##### Catalog Fetch Paginated ```none -GET /v2/_catalog?n=&last= +GET /v2/_catalog?n=&last= ``` - Return the specified portion of repositories. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4907,9 +5019,43 @@ Content-Type: application/json } ``` + + The following headers will be returned with the response: |Name|Description| |----|-----------| |`Content-Length`|Length of the JSON response body.| |`Link`|RFC5988 compliant rel='next' with URL to next result set, if available| + + +###### On Failure: Invalid pagination number + +```none +400 Bad Request +Content-Type: application/json + +{ + "errors": [ + { + "code": , + "message": "", + "detail": ... + }, + ... + ] +} +``` + +The received parameter n was invalid in some way, as described by the error code. The client should resolve the issue and retry the request. + +The error codes that may be included in the response body are enumerated below: + +|Code|Message|Description| +|----|-------|-----------| +| `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, "n" is negative or "n" is bigger than the maximum allowed. | + + + + + diff --git a/docs/content/spec/api.md.tmpl b/docs/content/spec/api.md.tmpl index fc0532126..c1bea8523 100644 --- a/docs/content/spec/api.md.tmpl +++ b/docs/content/spec/api.md.tmpl @@ -6,8 +6,6 @@ aliases: - /reference/api/registry_api/ --- -# Docker Registry HTTP API V2 - ## Introduction The _Docker Registry HTTP API_ is the protocol to facilitate distribution of @@ -212,7 +210,9 @@ layout of the new API is structured to support a rich authentication and authorization model by leveraging namespaces. All endpoints will be prefixed by the API version and the repository name: - /v2// +```none +/v2// +``` For example, an API endpoint that will work with the `library/ubuntu` repository, the URI prefix will be: @@ -252,8 +252,10 @@ Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses, in a json response body. One or more errors will be returned in the following format: +```none { - "errors:" [{ + "errors": [ + { "code": , "message": , "detail": @@ -261,6 +263,7 @@ errors will be returned in the following format: ... ] } +``` The `code` field will be a unique identifier, all caps with underscores by convention. The `message` field will be a human readable string. The optional @@ -281,7 +284,9 @@ section. A minimal endpoint, mounted at `/v2/` will provide version support information based on its response statuses. The request format is as follows: - GET /v2/ +```none +GET /v2/ +``` If a `200 OK` response is returned, the registry implements the V2(.1) registry API and the client may proceed safely with other V2 operations. @@ -304,7 +309,7 @@ API. When this header is omitted, clients may fallback to an older API version. ### Content Digests -This API design is driven heavily by [content addressability](http://en.wikipedia.org/wiki/Content-addressable_storage). +This API design is driven heavily by [content addressability](https://en.wikipedia.org/wiki/Content-addressable_storage). The core of this design is the concept of a content addressable identifier. It uniquely identifies content by taking a collision-resistant hash of the bytes. Such an identifier can be independently calculated and verified by selection @@ -402,7 +407,7 @@ the V2 registry API, keyed by their digest. The image manifest can be fetched with the following url: -``` +```none GET /v2//manifests/ ``` @@ -410,29 +415,29 @@ The `name` and `reference` parameter identify the image and are required. The reference may include a tag or digest. The client should include an Accept header indicating which manifest content -types it supports. For more details on the manifest formats and their content -types, see [manifest-v2-1.md](manifest-v2-1.md) and -[manifest-v2-2.md](manifest-v2-2.md). In a successful response, the Content-Type -header will indicate which manifest type is being returned. +types it supports. For more details on the manifest format and content types, +see [Image Manifest Version 2, Schema 2](manifest-v2-2.md). +In a successful response, the Content-Type header will indicate which manifest type is being returned. A `404 Not Found` response will be returned if the image is unknown to the registry. If the image exists and the response is successful, the image manifest will be returned, with the following format (see [docker/docker#8093](https://github.com/docker/docker/issues/8093) for details): - { - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": - }, - ... - ] - ], - "history": , - "signature": - } +```none +{ + "name": , + "tag": , + "fsLayers": [ + { + "blobSum": + }, + ... + ], + "history": , + "signature": +} +``` The client should verify the returned manifest signature for authenticity before fetching layers. @@ -441,7 +446,7 @@ before fetching layers. The image manifest can be checked for existence with the following url: -``` +```none HEAD /v2//manifests/ ``` @@ -452,13 +457,12 @@ A `404 Not Found` response will be returned if the image is unknown to the registry. If the image exists and the response is successful the response will be as follows: -``` +```none 200 OK Content-Length: Docker-Content-Digest: ``` - #### Pulling a Layer Layers are stored in the blob portion of the registry, keyed by digest. @@ -496,14 +500,14 @@ Uploads are started with a POST request which returns a url that can be used to push data and check upload status. The `Location` header will be used to communicate the upload location after -each request. While it won't change in the this specification, clients should +each request. While it won't change in this specification, clients should use the most recent value returned by the API. ##### Starting An Upload To begin the process, a POST request should be issued in the following format: -``` +```none POST /v2//blobs/uploads/ ``` @@ -515,7 +519,7 @@ will be linked. Responses to this request are covered below. The existence of a layer can be checked via a `HEAD` request to the blob store API. The request should be formatted as follows: -``` +```none HEAD /v2//blobs/ ``` @@ -523,7 +527,7 @@ If the layer with the digest specified in `digest` is available, a 200 OK response will be received, with no actual body content (this is according to http specification). The response will look as follows: -``` +```none 200 OK Content-Length: Docker-Content-Digest: @@ -539,7 +543,7 @@ for the existing registry layer, but the digests will be guaranteed to match. If the POST request is successful, a `202 Accepted` response will be returned with the upload URL in the `Location` header: -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- @@ -568,20 +572,20 @@ header, there are examples of [similar approaches](https://developers.google.com For an upload that just started, for an example with a 1000 byte layer file, the `Range` header would be as follows: -``` +```none Range: bytes=0-0 ``` To get the status of an upload, issue a GET request to the upload URL: -``` +```none GET /v2//blobs/uploads/ Host: ``` The response will be similar to the above, except will return 204 status: -``` +```none 204 No Content Location: /v2//blobs/uploads/ Range: bytes=0- @@ -598,7 +602,7 @@ favored by clients that would like to avoided the complexity of chunking. To carry out a "monolithic" upload, one can simply put the entire content blob to the provided URL: -``` +```none PUT /v2//blobs/uploads/?digest= Content-Length: Content-Type: application/octet-stream @@ -615,7 +619,7 @@ and expected responses. To carry out an upload of a chunk, the client can specify a range header and only include that part of the layer file: -``` +```none PATCH /v2//blobs/uploads/ Content-Length: Content-Range: - @@ -630,7 +634,7 @@ server cannot accept the chunk, a `416 Requested Range Not Satisfiable` response will be returned and will include a `Range` header indicating the current status: -``` +```none 416 Requested Range Not Satisfiable Location: /v2//blobs/uploads/ Range: 0- @@ -649,7 +653,7 @@ following conditions: When a chunk is accepted as part of the upload, a `202 Accepted` response will be returned, including a `Range` header with the current upload status: -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- @@ -664,7 +668,7 @@ request on the upload endpoint with a digest parameter. If it is not provided, the upload will not be considered complete. The format for the final chunk will be as follows: -``` +```none PUT /v2//blobs/uploads/?digest= Content-Length: Content-Range: - @@ -682,7 +686,7 @@ client if the content is rejected. When the last chunk is received and the layer has been validated, the client will receive a `201 Created` response: -``` +```none 201 Created Location: /v2//blobs/ Content-Length: 0 @@ -701,7 +705,7 @@ The "digest" parameter is designed as an opaque parameter to support verification of a successful transfer. For example, an HTTP URI parameter might be as follows: -``` +```none sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b ``` @@ -713,7 +717,7 @@ match this digest. An upload can be cancelled by issuing a DELETE request to the upload endpoint. The format will be as follows: -``` +```none DELETE /v2//blobs/uploads/ ``` @@ -729,7 +733,7 @@ to, removing the need to upload a blob already known to the registry. To issue a blob mount instead of an upload, a POST request should be issued in the following format: -``` +```none POST /v2//blobs/uploads/?mount=&from= Content-Length: 0 ``` @@ -737,7 +741,7 @@ Content-Length: 0 If the blob is successfully mounted, the client will receive a `201 Created` response: -``` +```none 201 Created Location: /v2//blobs/ Content-Length: 0 @@ -754,7 +758,7 @@ If a mount fails due to invalid repository or digest arguments, the registry will fall back to the standard upload behavior and return a `202 Accepted` with the upload URL in the `Location` header: -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- @@ -765,9 +769,11 @@ Docker-Upload-UUID: This behavior is consistent with older versions of the registry, which do not recognize the repository mount query parameters. -Note: a client may issue a HEAD request to check existence of a blob in a source +{{ "{{< hint type=note >}}" }} +A client may issue a HEAD request to check existence of a blob in a source repository to distinguish between the registry not supporting blob mounts and the blob not existing in the expected repository. +{{ "{{< /hint >}}" }} ##### Errors @@ -789,13 +795,17 @@ client must restart the upload process. A layer may be deleted from the registry via its `name` and `digest`. A delete may be issued with the following request format: - DELETE /v2//blobs/ +```none +DELETE /v2//blobs/ +``` If the blob exists and has been successfully deleted, the following response will be issued: - 202 Accepted - Content-Length: None +```none +202 Accepted +Content-Length: None +``` If the blob had already been deleted or did not exist, a `404 Not Found` response will be issued instead. @@ -808,28 +818,29 @@ then the complete images will not be resolvable. Once all of the layers for an image are uploaded, the client can upload the image manifest. An image can be pushed using the following request format: - PUT /v2//manifests/ - Content-Type: +```none +PUT /v2//manifests/ +Content-Type: - { - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": - }, - ... - ] - ], - "history": , - "signature": , - ... - } +{ + "name": , + "tag": , + "fsLayers": [ + { + "blobSum": + }, + ... + ], + "history": , + "signature": , + ... +} +``` The `name` and `reference` fields of the response body must match those specified in the URL. The `reference` field may be a "tag" or a "digest". The content type should match the type of the manifest being uploaded, as specified -in [manifest-v2-1.md](manifest-v2-1.md) and [manifest-v2-2.md](manifest-v2-2.md). +in [Image Manifest Version 2, Schema 2](manifest-v2-2.md). If there is a problem with pushing the manifest, a relevant 4xx response will be returned with a JSON error message. Please see the @@ -841,17 +852,20 @@ returned. The `detail` field of the error response will have a `digest` field identifying the missing blob. An error is returned for each unknown blob. The response format is as follows: - { - "errors:" [{ - "code": "BLOB_UNKNOWN", - "message": "blob unknown to registry", - "detail": { - "digest": - } - }, - ... - ] - } +```none +{ + "errors": [ + { + "code": "BLOB_UNKNOWN", + "message": "blob unknown to registry", + "detail": { + "digest": + } + }, + ... + ] +} +``` ### Listing Repositories @@ -862,21 +876,21 @@ available through the _catalog_. The catalog for a given registry can be retrieved with the following request: -``` +```none GET /v2/_catalog ``` The response will be in the following format: -``` +```none 200 OK Content-Type: application/json { - "repositories": [ - , - ... - ] + "repositories": [ + , + ... + ] } ``` @@ -906,7 +920,7 @@ Paginated catalog results can be retrieved by adding an `n` parameter to the request URL, declaring that the response should be limited to `n` results. Starting a paginated flow begins as follows: -``` +```none GET /v2/_catalog?n= ``` @@ -914,16 +928,16 @@ The above specifies that a catalog response should be returned, from the start o the result set, ordered lexically, limiting the number of results to `n`. The response to such a request would look as follows: -``` +```none 200 OK Content-Type: application/json Link: <?n=&last=>; rel="next" { - "repositories": [ - , - ... - ] + "repositories": [ + , + ... + ] } ``` @@ -950,7 +964,7 @@ to skip forward in the catalog. To get the next result set, a client would issue the request as follows, using the URL encoded in the described `Link` header: -``` +```none GET /v2/_catalog?n=&last= ``` @@ -965,7 +979,7 @@ entries. The behavior of `last` is quite simple when demonstrated with an example. Let us say the registry has the following repositories: -``` +```none a b c @@ -976,7 +990,7 @@ If the value of `n` is 2, _a_ and _b_ will be returned on the first response. The `Link` header returned on the response will have `n` set to 2 and last set to _b_: -``` +```none Link: <?n=2&last=b>; rel="next" ``` @@ -1016,7 +1030,7 @@ any differences. Starting a paginated flow may begin as follows: -``` +```none GET /v2//tags/list?n= ``` @@ -1024,17 +1038,17 @@ The above specifies that a tags response should be returned, from the start of the result set, ordered lexically, limiting the number of results to `n`. The response to such a request would look as follows: -``` +```none 200 OK Content-Type: application/json Link: <?n=&last=>; rel="next" { - "name": , - "tags": [ - , - ... - ] + "name": , + "tags": [ + , + ... + ] } ``` @@ -1042,7 +1056,7 @@ To get the next result set, a client would issue the request as follows, using the value encoded in the [RFC5988](https://tools.ietf.org/html/rfc5988) `Link` header: -``` +```none GET /v2//tags/list?n=&last= ``` @@ -1074,23 +1088,27 @@ response will be issued instead. Accept: application/vnd.docker.distribution.manifest.v2+json -> for more details, see: [compatibility.md](../compatibility.md#content-addressable-storage-cas) +> for more details, see: [compatibility](../about/compatibility.md#content-addressable-storage-cas) ## Detail -> **Note**: This section is still under construction. For the purposes of -> implementation, if any details below differ from the described request flows -> above, the section below should be corrected. When they match, this note -> should be removed. +{{ "{{< hint type=note >}}" }} +This section is still under construction. For the purposes of +implementation, if any details below differ from the described request flows +above, the section below should be corrected. When they match, this note +should be removed. +{{ "{{< /hint >}}" }} The behavior of the endpoints are covered in detail in this section, organized by route and entity. All aspects of the request and responses are covered, including headers, parameters and body formats. Examples of requests and their corresponding responses, with success and failure, are enumerated. -> **Note**: The sections on endpoint detail are arranged with an example -> request, a description of the request, followed by information about that -> request. +{{ "{{< hint type=note >}}" }} +The sections on endpoint detail are arranged with an example +request, a description of the request, followed by information about that +request. +{{ "{{< /hint >}}" }} A list of methods and URIs are covered in the table below: @@ -1098,7 +1116,6 @@ A list of methods and URIs are covered in the table below: |------|----|------|-----------| {{range $route := .RouteDescriptors}}{{range $method := .Methods}}| {{$method.Method}} | `{{$route.Path|prettygorilla}}` | {{$route.Entity}} | {{$method.Description}} | {{end}}{{end}} - The detail for each endpoint is covered in the following sections. ### Errors @@ -1108,33 +1125,30 @@ The error codes encountered via the API are enumerated in the following table: |Code|Message|Description| |----|-------|-----------| {{range $err := .ErrorDescriptors}} `{{$err.Value}}` | {{$err.Message}} | {{$err.Description|removenewlines}} -{{end}} - -{{range $route := .RouteDescriptors}} +{{end -}} +{{range $route := .RouteDescriptors -}} ### {{.Entity}} {{.Description}} -{{range $method := $route.Methods}} - +{{range $method := $route.Methods -}} #### {{.Method}} {{$route.Entity}} -{{.Description}} +{{.Description -}} {{if .Requests}}{{range .Requests}}{{if .Name}} -##### {{.Name}}{{end}} +##### {{ .Name}}{{end }} -``` +```none {{$method.Method}} {{$route.Path|prettygorilla}}{{range $i, $param := .QueryParameters}}{{if eq $i 0}}?{{else}}&{{end}}{{$param.Name}}={{$param.Format}}{{end}}{{range .Headers}} {{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}} Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} {{.Body.Format}}{{end}} ``` +{{.Description -}} -{{.Description}} - -{{if or .Headers .PathParameters .QueryParameters}} +{{ if or .Headers .PathParameters .QueryParameters }} The following parameters should be specified on the request: |Name|Kind|Description| @@ -1142,39 +1156,43 @@ The following parameters should be specified on the request: {{range .Headers}}|`{{.Name}}`|header|{{.Description}}| {{end}}{{range .PathParameters}}|`{{.Name}}`|path|{{.Description}}| {{end}}{{range .QueryParameters}}|`{{.Name}}`|query|{{.Description}}| -{{end}}{{end}} +{{end}}{{end -}} -{{if .Successes}} -{{range .Successes}} +{{if .Successes -}} +{{range .Successes }} ###### On Success: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}} -``` -{{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}} +```none +{{.StatusCode }} {{.StatusCode | statustext }} +{{- range .Headers }} {{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}} Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} {{.Body.Format}}{{end}} ``` -{{.Description}} +{{.Description -}} {{if .Fields}}The following fields may be returned in the response body: |Name|Description| |----|-----------| {{range .Fields}}|`{{.Name}}`|{{.Description}}| {{end}}{{end}}{{if .Headers}} + The following headers will be returned with the response: |Name|Description| |----|-----------| -{{range .Headers}}|`{{.Name}}`|{{.Description}}| +{{range .Headers -}} +|`{{.Name}}`|{{.Description -}}| {{end}}{{end}}{{end}}{{end}} -{{if .Failures}} -{{range .Failures}} +{{if .Failures -}} +{{range .Failures -}} + ###### On Failure: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}} -``` +```none {{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}} {{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}} Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}} @@ -1189,9 +1207,8 @@ The following headers will be returned on the response: |Name|Description| |----|-----------| {{range .Headers}}|`{{.Name}}`|{{.Description}}| -{{end}}{{end}} - -{{if .ErrorCodes}} +{{end}}{{end }} +{{if .ErrorCodes -}} The error codes that may be included in the response body are enumerated below: |Code|Message|Description| diff --git a/registry/api/v2/descriptors.go b/registry/api/v2/descriptors.go index cf000b274..16b9cffeb 100644 --- a/registry/api/v2/descriptors.go +++ b/registry/api/v2/descriptors.go @@ -223,21 +223,20 @@ var ( const ( manifestBody = `{ - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": "" - }, - ... - ] - ], - "history": , - "signature": + "name": , + "tag": , + "fsLayers": [ + { + "blobSum": "" + }, + ... + ], + "history": , + "signature": }` errorsBody = `{ - "errors:" [ + "errors": [ { "code": , "message": "", @@ -640,7 +639,8 @@ var routeDescriptors = []RouteDescriptor{ Body: BodyDescriptor{ ContentType: "application/json", Format: `{ - "errors:" [{ + "errors": [ + { "code": "BLOB_UNKNOWN", "message": "blob unknown to registry", "detail": { @@ -1567,7 +1567,7 @@ var routeDescriptors = []RouteDescriptor{ "repositories": [ , ... - ] + ], }`, }, }, @@ -1586,7 +1586,7 @@ var routeDescriptors = []RouteDescriptor{ "repositories": [ , ... - ] + ], "next": "?last=&n=" }`, },