diff --git a/content/docker-hub/api/dvp.yaml b/content/docker-hub/api/dvp.yaml index fcecb71d3f..e30353aded 100644 --- a/content/docker-hub/api/dvp.yaml +++ b/content/docker-hub/api/dvp.yaml @@ -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 diff --git a/content/engine/api/_index.md b/content/engine/api/_index.md index 1143d36886..0626ddb42a 100644 --- a/content/engine/api/_index.md +++ b/content/engine/api/_index.md @@ -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) \ No newline at end of file +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) \ No newline at end of file diff --git a/content/engine/api/sdk/_index.md b/content/engine/api/sdk/_index.md index a4d333acae..0e42c6459b 100644 --- a/content/engine/api/sdk/_index.md +++ b/content/engine/api/sdk/_index.md @@ -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://` instead, -> for example, `http:/v{{% param "latest_engine_api_version" %}}/containers/1c6594faf5/start` +> +> If you're' using an older version of cURL, use `http://` 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 | diff --git a/content/engine/api/sdk/examples.md b/content/engine/api/sdk/examples.md index 84adbda879..008242fad7 100644 --- a/content/engine/api/sdk/examples.md +++ b/content/engine/api/sdk/examples.md @@ -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://` instead, -> for example, `http:/v{{% param "latest_engine_api_version" %}}/containers/1c6594faf5/start` +> +> If you're' using an older version of cURL, use `http://` 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