From a9d347d9e40547983ae0b841bc150609221f9814 Mon Sep 17 00:00:00 2001 From: Laura Brehm Date: Thu, 21 Nov 2024 16:47:11 +0000 Subject: [PATCH] docs/api: document `/_ping?capabilities=v1` endpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We've added a query parameter `capabilities` to the `/_ping` endpoint that allows clients to request capabilities that the engine supports in the `/_ping` response. Document this change in `docs/api/version-history.md`, and update the swagger yaml accordingly. For Swagger, I've added a "separate" endpoint documenting the new behavior. This has to do with Swagger not supporting different responses for the same path (either based on query params or content-types/other headers) – see https://github.com/OAI/OpenAPI-Specification/issues/146 This is supported in OpenAPI 3.0 (https://github.com/OAI/OpenAPI-Specification/issues/146#issuecomment-256648748), so we could fix this up in the future. Signed-off-by: Laura Brehm --- api/swagger.yaml | 87 +++++++++++++++++++++++++++++++++++++ docs/api/version-history.md | 4 ++ 2 files changed, 91 insertions(+) diff --git a/api/swagger.yaml b/api/swagger.yaml index b9f805a52f73d..fbf63ac970226 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -173,6 +173,16 @@ tags: x-displayName: "System" definitions: + Capabilities: + description: "Represents engine capabilities" + type: "object" + properties: + registry-client-auth: + description: "Whether the engine supports client auth handling." + type: "boolean" + x-nullable: false + example: + registry-client-auth: true Port: type: "object" description: "An open port on a container" @@ -9709,6 +9719,83 @@ paths: schema: $ref: "#/definitions/ErrorResponse" tags: ["System"] + # Using a zero-width character here to define a separate /_ping endpoint to describe the + # /_ping?capabilities=v1 API since otherwise Swagger won't allow us to define multiple + # responses for the same endpoint depending on query parameter. + # This is however supported by OpenAPI v3. + # See: https://github.com/OAI/OpenAPI-Specification/issues/146 + # and https://github.com/OAI/OpenAPI-Specification/issues/182 + /_ping​: + get: + summary: "/_ping?capabilities=v1" + description: | + This is the same endpoint as `GET /_ping`, but describes the different + response when it is called with the `capabilities=v1` query parameter. + + In this case, the daemon instead responds with a `Content-Type` of + `application/json` and writes a json represenation of the engine's + capabilities in the response body. + operationId: "SystemPingCapabilities" + produces: ["application/json"] + parameters: + - name: "capabilities" + in: "query" + description: | + TODO + # marked as required since this is a separate endpoint in the swagger yaml. + required: true + type: "string" + enum: ["v1"] + responses: + 200: + description: "no error" + schema: + $ref: "#/definitions/Capabilities" + headers: + API-Version: + type: "string" + description: "Max API Version the server supports" + Builder-Version: + type: "string" + description: | + Default version of docker image builder + + The default on Linux is version "2" (BuildKit), but the daemon + can be configured to recommend version "1" (classic Builder). + Windows does not yet support BuildKit for native Windows images, + and uses "1" (classic builder) as a default. + + This value is a recommendation as advertised by the daemon, and + it is up to the client to choose which builder to use. + default: "2" + Docker-Experimental: + type: "boolean" + description: "If the server is running with experimental mode enabled" + Swarm: + type: "string" + enum: ["inactive", "pending", "error", "locked", "active/worker", "active/manager"] + description: | + Contains information about Swarm status of the daemon, + and if the daemon is acting as a manager or worker node. + default: "inactive" + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + headers: + Cache-Control: + type: "string" + default: "no-cache, no-store, must-revalidate" + Pragma: + type: "string" + default: "no-cache" + tags: ["System"] /commit: post: summary: "Create a new image from a container" diff --git a/docs/api/version-history.md b/docs/api/version-history.md index 52f80ee973809..99a8f23ec5e6d 100644 --- a/docs/api/version-history.md +++ b/docs/api/version-history.md @@ -62,6 +62,10 @@ keywords: "API, Docker, rcli, REST, documentation" `GET /debug/pprof/profile`, `GET /debug/pprof/symbol`, `GET /debug/pprof/trace`, `GET /debug/pprof/{name}`) are now also accessible through the versioned-API paths (`/v/`). +* `GET` `/_ping` endpoint now optionally supports a `capabilities` query parameter + (e.g. `GET /_ping?capabilities=1`). If set, instead of the response body containing + `OK`, the daemon responds with a JSON Content-Type instead of `text/plain`, and + includes the engine capabilities in the response. ## v1.47 API changes