mirror of https://github.com/docker/docs.git
Reference freshness updates (#18966)
* update punctuation and grammar * refresh engine api overview * update metadata and refresh engine sdk overview * update callouts and refresh sdk examples * update word * fix callout * fix callout pt two
This commit is contained in:
Stephanie Aurelio
GitHub
parent
091232d4fc
commit
f4d58b3958
|
|
@ -134,7 +134,7 @@ paths:
|
|||
security: []
|
||||
tags:
|
||||
- authentication
|
||||
summary: Second factor authentication.
|
||||
summary: Second factor authentication
|
||||
operationId: PostUsers2FALogin
|
||||
description: |
|
||||
When a user has 2FA enabled, this is the second call to perform after
|
||||
|
|
@ -171,7 +171,7 @@ paths:
|
|||
get:
|
||||
tags: [discovery]
|
||||
summary: Get namespaces and repos
|
||||
description: Gets a list of your namespaces and repos which have data available
|
||||
description: Gets a list of your namespaces and repos which have data available.
|
||||
operationId: getNamespaces
|
||||
responses:
|
||||
'200':
|
||||
|
|
@ -184,7 +184,7 @@ paths:
|
|||
get:
|
||||
tags: [discovery]
|
||||
summary: Get user's namespaces
|
||||
description: Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces
|
||||
description: Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces.
|
||||
operationId: getUserNamespaces
|
||||
responses:
|
||||
'200':
|
||||
|
|
@ -201,7 +201,7 @@ paths:
|
|||
get:
|
||||
tags: [discovery]
|
||||
summary: Get namespace
|
||||
description: Gets metadata associated with specified namespace, including extra repos associated with the namespace
|
||||
description: Gets metadata associated with specified namespace, including extra repos associated with the namespace.
|
||||
operationId: getNamespace
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -221,7 +221,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get pull data
|
||||
description: Gets pull for the given namespace
|
||||
description: Gets pulls for the given namespace.
|
||||
operationId: getNamespacePulls
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -261,7 +261,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get pull data
|
||||
description: Gets pull for the given repo
|
||||
description: Gets pulls for the given repo.
|
||||
operationId: getRepoPulls
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -307,7 +307,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get years with data
|
||||
description: Gets a list of years that have data for the given namespace
|
||||
description: Gets a list of years that have data for the given namespace.
|
||||
operationId: getNamespaceYears
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -327,7 +327,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get timespans with data
|
||||
description: Gets a list of timespans of the given type that have data for the given namespace and year
|
||||
description: Gets a list of timespans of the given type that have data for the given namespace and year.
|
||||
operationId: getNamespaceTimespans
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -359,7 +359,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get namespace metadata for timespan
|
||||
description: Gets info about data for the given namespace and timespan
|
||||
description: Gets info about data for the given namespace and timespan.
|
||||
operationId: getNamespaceTimespanMetadata
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -399,7 +399,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get namespace data for timespan
|
||||
description: Gets a list of URLs that can be used to download the pull data for the given namespace and timespan
|
||||
description: Gets a list of URLs that can be used to download the pull data for the given namespace and timespan.
|
||||
operationId: getNamespaceDataByTimespan
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -443,7 +443,7 @@ paths:
|
|||
get:
|
||||
tags: [namespaces]
|
||||
summary: Get pull data for multiple repos
|
||||
description: Gets pull for the given repos
|
||||
description: Gets pull for the given repos.
|
||||
operationId: getManyReposPulls
|
||||
parameters:
|
||||
- in: query
|
||||
|
|
@ -524,7 +524,7 @@ components:
|
|||
nullable: false
|
||||
login_2fa_token:
|
||||
description:
|
||||
Short time lived token to be used on `/v2/users/2fa-login` to
|
||||
Short-lived token to be used on `/v2/users/2fa-login` to
|
||||
complete the authentication. This field is present only if 2FA is
|
||||
enabled.
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Develop with Docker Engine API
|
||||
description: Using Docker APIs to automate Docker tasks in your language of choice
|
||||
keywords: developing, api
|
||||
description: Learn how you can use Docker Engine API and SDKs in the language of your choice.
|
||||
keywords: developing, api, Docker Engine API, API versions, SDK versions
|
||||
aliases:
|
||||
- /engine/reference/api/
|
||||
- /engine/reference/api/docker_remote_api/
|
||||
|
|
@ -28,8 +28,8 @@ aliases:
|
|||
---
|
||||
|
||||
Docker provides an API for interacting with the Docker daemon (called the Docker
|
||||
Engine API), as well as SDKs for Go and Python. The SDKs allow you to build and
|
||||
scale Docker apps and solutions quickly and easily. If Go or Python don't work
|
||||
Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and
|
||||
scale Docker apps and solutions. If Go or Python don't work
|
||||
for you, you can use the Docker Engine API directly.
|
||||
|
||||
For information about Docker Engine SDKs, see [Develop with Docker Engine SDKs](sdk/index.md).
|
||||
|
|
@ -52,19 +52,19 @@ A given version of the Docker Engine SDK supports a specific version of the
|
|||
Docker Engine API, as well as all earlier versions. If breaking changes occur,
|
||||
they are documented prominently.
|
||||
|
||||
> Daemon and client API mismatches
|
||||
> **Note**
|
||||
>
|
||||
> The Docker daemon and client do not necessarily need to be the same version
|
||||
> The Docker daemon and client don't necessarily need to be the same version
|
||||
> at all times. However, keep the following in mind.
|
||||
>
|
||||
> - If the daemon is newer than the client, the client does not know about new
|
||||
> - If the daemon is newer than the client, the client doesn't know about new
|
||||
> features or deprecated API endpoints in the daemon.
|
||||
>
|
||||
> - If the client is newer than the daemon, the client can request API
|
||||
> endpoints that the daemon does not know about.
|
||||
> endpoints that the daemon doesn't know about.
|
||||
|
||||
A new version of the API is released when new features are added. The Docker API
|
||||
is backward-compatible, so you do not need to update code that uses the API
|
||||
is backward-compatible, so you don't need to update code that uses the API
|
||||
unless you need to take advantage of new features.
|
||||
|
||||
To see the highest version of the API your Docker daemon and client support, use
|
||||
|
|
@ -93,14 +93,14 @@ Server: Docker Engine - Community
|
|||
...
|
||||
```
|
||||
|
||||
You can specify the API version to use, in one of the following ways:
|
||||
You can specify the API version to use in any of the following ways:
|
||||
|
||||
- When using the SDK, use the latest version you can, but at least the version
|
||||
- When using the SDK, use the latest version. At a minimum, use the version
|
||||
that incorporates the API version with the features you need.
|
||||
- When using `curl` directly, specify the version as the first part of the URL.
|
||||
For instance, if the endpoint is `/containers/` you can use
|
||||
`/v1.42/containers/`.
|
||||
- To force the Docker CLI or the Docker Engine SDKs to use an old version
|
||||
- To force the Docker CLI or the Docker Engine SDKs to use an older version
|
||||
of the API than the version reported by `docker version`, set the
|
||||
environment variable `DOCKER_API_VERSION` to the correct version. This works
|
||||
on Linux, Windows, or macOS clients.
|
||||
|
|
@ -111,13 +111,13 @@ You can specify the API version to use, in one of the following ways:
|
|||
|
||||
While the environment variable is set, that version of the API is used, even
|
||||
if the Docker daemon supports a newer version. This environment variable
|
||||
disables API version negotiation, and as such should only be used if you must
|
||||
disables API version negotiation, so you should only use it if you must
|
||||
use a specific version of the API, or for debugging purposes.
|
||||
|
||||
- The Docker Go SDK allows you to enable API version negotiation, automatically
|
||||
selects an API version that is supported by both the client, and the Docker Engine
|
||||
that is used.
|
||||
- For the SDKs, you can also specify the API version programmatically, as a
|
||||
selects an API version that's supported by both the client and the Docker Engine
|
||||
that's in use.
|
||||
- For the SDKs, you can also specify the API version programmatically as a
|
||||
parameter to the `client` object. See the
|
||||
[Go constructor](https://pkg.go.dev/github.com/docker/docker/client#NewClientWithOpts)
|
||||
or the
|
||||
|
|
@ -129,5 +129,5 @@ You can specify the API version to use, in one of the following ways:
|
|||
|
||||
### Archived API versions
|
||||
|
||||
Documentation for older versions of the API has been archived, but can be found
|
||||
in the [docker code repository on GitHub](https://github.com/moby/moby/tree/v1.9.1/docs/reference/api)
|
||||
You can find archived documentation for older versions of the API
|
||||
in the [Docker code repository on GitHub](https://github.com/moby/moby/tree/v1.9.1/docs/reference/api)
|
||||
|
|
@ -1,15 +1,15 @@
|
|||
---
|
||||
title: Develop with Docker Engine SDKs
|
||||
description: Using Docker SDKs to automate Docker tasks in your language of choice
|
||||
keywords: developing, sdk
|
||||
description: Learn how to use Docker Engine SDKs to automate Docker tasks in your language of choice
|
||||
keywords: developing, sdk, Docker Engine SDKs, install SDKs, SDK versions
|
||||
aliases:
|
||||
- /engine/api/sdks/
|
||||
- /develop/sdk/
|
||||
---
|
||||
|
||||
Docker provides an API for interacting with the Docker daemon (called the Docker
|
||||
Engine API), as well as SDKs for Go and Python. The SDKs allow you to build and
|
||||
scale Docker apps and solutions quickly and easily. If Go or Python don't work
|
||||
Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and
|
||||
scale Docker apps and solutions. If Go or Python don't work
|
||||
for you, you can use the Docker Engine API directly.
|
||||
|
||||
The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or
|
||||
|
|
@ -26,23 +26,22 @@ installed and coexist together.
|
|||
$ go get github.com/docker/docker/client
|
||||
```
|
||||
|
||||
The client requires a recent version of Go. Run `go version` and ensure that you
|
||||
are running a currently supported version of Go
|
||||
The client requires a recent version of Go. Run `go version` and ensure that you're running a currently supported version of Go.
|
||||
|
||||
|
||||
[Read the full Docker Engine Go SDK reference](https://godoc.org/github.com/docker/docker/client).
|
||||
For more information, see [Docker Engine Go SDK reference](https://godoc.org/github.com/docker/docker/client).
|
||||
|
||||
### Python SDK
|
||||
|
||||
- **Recommended**: Run `pip install docker`.
|
||||
- Recommended: Run `pip install docker`.
|
||||
|
||||
- **If you can't use `pip`**:
|
||||
- If you can't use `pip`:
|
||||
|
||||
1. [Download the package directly](https://pypi.python.org/pypi/docker/).
|
||||
2. Extract it and change to the extracted directory,
|
||||
2. Extract it and change to the extracted directory.
|
||||
3. Run `python setup.py install`.
|
||||
|
||||
[Read the full Docker Engine Python SDK reference](https://docker-py.readthedocs.io/).
|
||||
For more information, see [Docker Engine Python SDK reference](https://docker-py.readthedocs.io/).
|
||||
|
||||
## View the API reference
|
||||
|
||||
|
|
@ -52,8 +51,8 @@ or [choose a specific version](/engine/api/version-history/).
|
|||
|
||||
## Versioned API and SDK
|
||||
|
||||
The version of the Docker Engine API you should use depends upon the version of
|
||||
your Docker daemon and Docker client. Refer to the [versioned API and SDK](/engine/api/#versioned-api-and-sdk)
|
||||
The version of the Docker Engine API you should use depends on the version of
|
||||
your Docker daemon and Docker client. See the [versioned API and SDK](/engine/api/#versioned-api-and-sdk)
|
||||
section in the API documentation for details.
|
||||
|
||||
## SDK and API quickstart
|
||||
|
|
@ -68,7 +67,7 @@ code:
|
|||
that supports the feature, and prefer the latest version you can use.
|
||||
- Otherwise, continue to use the version that your code is already using.
|
||||
|
||||
As an example, the `docker run` command can be easily implemented using the
|
||||
As an example, the `docker run` command can be implemented using the
|
||||
Docker API directly, or using the Python or Go SDK.
|
||||
|
||||
{{< tabs >}}
|
||||
|
|
@ -159,17 +158,17 @@ $ curl --unix-socket /var/run/docker.sock "http://localhost/v{{% param "latest_e
|
|||
hello world
|
||||
```
|
||||
|
||||
When using cURL to connect over a Unix socket, the hostname is not important. The
|
||||
examples above use `localhost`, but any hostname would work.
|
||||
When using cURL to connect over a Unix socket, the hostname is not important. The previous
|
||||
examples use `localhost`, but any hostname would work.
|
||||
|
||||
> **Using cURL 7.47.0 or below?**
|
||||
> **Important**
|
||||
>
|
||||
> The examples above assume you are using cURL 7.50.0 or above. Older versions of
|
||||
> The previous examples assume you're using cURL 7.50.0 or above. Older versions of
|
||||
> cURL used a [non-standard URL notation](https://github.com/moby/moby/issues/17960)
|
||||
> when using a socket connection.
|
||||
>
|
||||
> If you are using an older version of cURL, use `http:/<API version>/` instead,
|
||||
> for example, `http:/v{{% param "latest_engine_api_version" %}}/containers/1c6594faf5/start`
|
||||
>
|
||||
> If you're' using an older version of cURL, use `http:/<API version>/` instead,
|
||||
> for example: `http:/v{{% param "latest_engine_api_version" %}}/containers/1c6594faf5/start`.
|
||||
{ .important }
|
||||
|
||||
{{< /tab >}}
|
||||
|
|
@ -180,7 +179,7 @@ For more examples, take a look at the [SDK examples](examples.md).
|
|||
## Unofficial libraries
|
||||
|
||||
There are a number of community supported libraries available for other
|
||||
languages. They have not been tested by Docker, so if you run into any issues,
|
||||
languages. They haven't been tested by Docker, so if you run into any issues,
|
||||
file them with the library maintainers.
|
||||
|
||||
| Language | Library |
|
||||
|
|
|
|||
|
|
@ -122,17 +122,17 @@ $ curl --unix-socket /var/run/docker.sock "http://localhost/v{{% param "latest_e
|
|||
hello world
|
||||
```
|
||||
|
||||
When using cURL to connect over a unix socket, the hostname is not important. The
|
||||
examples above use `localhost`, but any hostname would work.
|
||||
When using cURL to connect over a Unix socket, the hostname isn't important. The
|
||||
previous examples use `localhost`, but any hostname would work.
|
||||
|
||||
> **Using cURL 7.47.0 or below?**
|
||||
> **Important**
|
||||
>
|
||||
> The examples above assume you are using cURL 7.50.0 or above. Older versions of
|
||||
> The previous examples assume you're using cURL 7.50.0 or above. Older versions of
|
||||
> cURL used a [non-standard URL notation](https://github.com/moby/moby/issues/17960)
|
||||
> when using a socket connection.
|
||||
>
|
||||
> If you are using an older version of cURL, use `http:/<API version>/` instead,
|
||||
> for example, `http:/v{{% param "latest_engine_api_version" %}}/containers/1c6594faf5/start`
|
||||
>
|
||||
> If you're' using an older version of cURL, use `http:/<API version>/` instead,
|
||||
> for example: `http:/v{{% param "latest_engine_api_version" %}}/containers/1c6594faf5/start`.
|
||||
{ .important }
|
||||
|
||||
{{< /tab >}}
|
||||
|
|
@ -286,7 +286,9 @@ $ curl --unix-socket /var/run/docker.sock http://localhost/v{{% param "latest_en
|
|||
Now that you know what containers exist, you can perform operations on them.
|
||||
This example stops all running containers.
|
||||
|
||||
> **Note**: Don't run this on a production server. Also, if you are using swarm
|
||||
> **Note**
|
||||
>
|
||||
> Don't run this on a production server. Also, if you're' using swarm
|
||||
> services, the containers stop, but Docker creates new ones to keep
|
||||
> the service running in its configured state.
|
||||
|
||||
|
|
@ -552,7 +554,9 @@ $ curl --unix-socket /var/run/docker.sock \
|
|||
|
||||
Pull an image, like `docker pull`, with authentication:
|
||||
|
||||
> **Note**: Credentials are sent in the clear. Docker's official registries use
|
||||
> **Note**
|
||||
>
|
||||
> Credentials are sent in the clear. Docker's official registries use
|
||||
> HTTPS. Private registries should also be configured to use HTTPS.
|
||||
|
||||
{{< tabs group="lang" >}}
|
||||
|
|
@ -606,8 +610,8 @@ func main() {
|
|||
The Python SDK retrieves authentication information from the [credentials
|
||||
store](/engine/reference/commandline/login/#credentials-store) file and
|
||||
integrates with [credential
|
||||
helpers](https://github.com/docker/docker-credential-helpers). It is possible to override these credentials, but that is out of
|
||||
scope for this Getting Started guide. After using `docker login`, the Python SDK
|
||||
helpers](https://github.com/docker/docker-credential-helpers). It's possible to override these credentials, but that's out of
|
||||
scope for this example guide. After using `docker login`, the Python SDK
|
||||
uses these credentials automatically.
|
||||
|
||||
```python
|
||||
|
|
|
|||
Loading…
Reference in New Issue