{{ define "head-extra" }}

{{ $style := resources.Get "api-reference/reference.css" | fingerprint }}

<link rel="stylesheet" href="{{ $style.RelPermalink }}" />

{{ $script := resources.Get "api-reference/reference.js" | fingerprint }}

<script src="{{ $script.RelPermalink }}" defer></script>

{{ end }}

{{ define "left" }}

{{ partial "sidebar/mainnav.html" . }}

{{ if eq .Params.view "catalog" }}

{{ partial "sidebar/sections.html" . }}

{{ else }}

{{ partial "api-reference/navigation.html" . }}

{{ end }}

{{ end }}

{{ define "main" }}

<article class="api-reference" data-api-view="{{ .Params.view }}">

{{ $data := index hugo.Data "api-reference" }}

{{ $api := dict }}{{ range $data.apis }}

{{ if eq .id $.Params.apiID }}{{ $api = . }}{{ end }}

{{ end }}

{{ if eq .Params.view "catalog" }}

<p class="api-eyebrow">Developer reference</p>

<h1>Docker APIs</h1>

<p class="api-lead">

Build with Docker, from your local daemon to hosted services.

</p>

<p>

Choose an API to find connection guidance, operations, and data models.

</p>

<div class="api-cards">

{{ range $data.apis }}

<a class="api-card" href="{{ .url }}"

><span class="api-label"

>{{ if eq .connection "unix" }}

Your daemon

{{ else }}

Hosted service

{{ end }}</span

>

<h2>{{ .title }}{{ if .experimental }}· Experimental{{ end }}</h2>

<p>API {{ .version }} · {{ len .operations }} operations</p>

<span>Explore reference →</span></a

>

{{ end }}

{{ range $data.legacyAPIs }}

<a class="api-card" href="{{ .url }}">

<span class="api-label"

>{{ if eq .connection "unix" }}

Your daemon

{{ else }}

Hosted service

{{ end }}</span

>

<h2>{{ .title }}{{ if .experimental }}· Experimental{{ end }}</h2>

<p>{{ .description }}</p>

<span>Explore reference →</span>

</a>

{{ end }}

</div>

{{ else }}

<nav class="api-crumbs" aria-label="API breadcrumb">

<a href="/reference/api/">APIs</a> /

<a href="{{ $api.url }}">{{ $api.title }}</a> /

<span>API {{ $api.version }}</span>

</nav>

{{ if $api.experimental }}

<p class="api-label">Experimental</p>

{{ if eq .Params.view "overview" }}

<p>

This API is experimental. Features, interfaces, and behavior may

change.

</p>

{{ end }}

{{ end }}

<div class="api-tools">

<label

>API version

<select data-api-version>

{{ range $data.apis }}

{{ if eq .product $api.product }}

<option

value="{{ .url }}"

{{ if eq .id $api.id }}selected{{ end }}

>

{{ .version }}

</option>

{{ end }}

{{ end }}

</select></label

><a href="{{ ref . $api.manual }}">Product manual</a

><a href="{{ $api.sourceURL }}">Download OpenAPI specification</a

><a href="{{ partial "utils/markdown-url.html" . }}">Markdown</a>

</div>

<meta

data-pagefind-meta="title:{{ .Title }} — {{ $api.title }} API {{ $api.version }}"

/>

{{ if eq .Params.view "overview" }}

<p class="api-eyebrow">

{{ if eq $api.connection "unix" }}

User-operated API

{{ else }}

Hosted API

{{ end }}

</p>

<h1>{{ $api.title }} API</h1>

<p class="api-lead">

API {{ $api.version }} · {{ len $api.operations }} operations ·

{{ len $api.schemas }} named schemas

</p>

<section class="api-overview" aria-labelledby="api-overview-title">

<h2 id="api-overview-title">Overview</h2>

<div class="prose dark:prose-invert">

{{ partial "api-reference/description.html" (dict "text" $api.description "api" $api) | markdownify }}

</div>

</section>

<section class="api-connection" id="authentication">

<h2>

{{ if eq $api.connection "unix" }}

Connecting to

{{ $api.title }}

{{ else }}

Connecting to the {{ $api.title }} API

{{ end }}

</h2>

{{ range $name, $scheme := $api.securitySchemes }}

{{ with $scheme.description }}

<h3>{{ index $scheme "x-displayName" | default $name }}</h3>

<div class="prose dark:prose-invert">{{ . | markdownify }}</div>

{{ end }}

{{ end }}

{{ if eq $api.connection "unix" }}

<pre><code>curl --unix-socket /var/run/docker.sock http://localhost/v{{ $api.version }}/version</code></pre>

{{ else }}

{{ range $api.servers }}<code>{{ .url }}</code>{{ end }}

{{ end }}{{ range $api.guides }}

{{ $guide := site.GetPage (index (split . "#") 0) }}

<p><a href="{{ ref $ . }}">{{ $guide.Title }}</a></p>

{{ end }}

</section>

<div class="api-overview">

{{ $overviewTags := partial "api-reference/overview-tags.html" $api }}

{{ range $api.tags }}

{{ if not (in $overviewTags .) }}

<span id="tag-{{ .name | urlize }}"></span>

{{ end }}

{{ end }}

{{ range $overviewTags }}

<section id="tag-{{ .name | urlize }}">

<h2>{{ .summary }}</h2>

<div class="prose dark:prose-invert">

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) | markdownify }}

</div>

</section>

{{ end }}

</div>

<h2>Operations</h2>

<label class="api-filter-label"

>Filter operations

<input

type="search"

placeholder="Method, path, or operation name"

data-api-filter

/></label>

<div class="api-operation-list">

{{ range $api.operations }}

<a class="api-operation-row" href="{{ .url }}" data-api-filter-item

><span class="api-method" data-method="{{ .method }}"

>{{ .method }}</span

><code>{{ partial "api-reference/path.html" .path }}</code

><span>{{ .summary }}</span></a

>

{{ end }}

</div>

<h2 id="schemas">Schemas</h2>

<ul class="api-schema-links" aria-label="Schemas">

{{ range $api.schemas }}

<li>

<a href="{{ .url }}"><code>{{ .name }}</code></a>

</li>

{{ end }}

</ul>

{{ else if eq .Params.view "operation" }}

{{ range $api.operations }}

{{ if eq .id $.Params.operationID }}

<h1>{{ .summary }}</h1>

<div class="api-signature">

<span class="api-method" data-method="{{ .method }}"

>{{ .method }}</span

><code>{{ partial "api-reference/path.html" .path }}</code

>{{ if .deprecated }}

<span>Deprecated</span>

{{ end }}

</div>

<div class="api-operation-grid">

<div class="api-reading">

<div class="api-description prose dark:prose-invert">

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) | markdownify }}

</div>

<h2>Connection and access</h2>

<p>

<a href="{{ $api.url }}#authentication"

>API connection and authentication guidance</a

>

</p>

{{ if and (eq $api.product "engine") (where .parameters "name" "X-Registry-Auth") }}

<p>

<code>X-Registry-Auth</code> delegates registry credentials

and does not authenticate the daemon caller.

</p>

{{ end }}

{{ range .servers }}

<p>

<code>{{ .url }}</code>{{ with .description }}

—

{{ . }}

{{ end }}

</p>

{{ end }}

{{ range .servers }}

{{ range $name, $variable := .variables }}

<p><code>{{ $name }}</code>: {{ $variable.description }}</p>

{{ end }}

{{ end }}

{{ if not .security }}

<p>

No HTTP authentication requirement is declared for this

operation. Transport access controls can still apply.

</p>

{{ else }}

<p>

Use one of these alternatives. Requirements within an

alternative apply together.

</p>

<ul>

{{ range .security }}

<li>

{{ $first := true }}{{ range $name, $scopes := . }}

{{ if not $first }}

AND

{{ end }}{{ $first = false }}<code>{{ $name }}</code>{{ with $scopes }}

({{ delimit . ", " }})

{{ end }}

{{ end }}{{ if $first }}Anonymous access{{ end }}

</li>

{{ end }}

</ul>

{{ end }}

{{ with index .raw "x-websocket" }}

{{ partial "api-reference/websocket.html" (dict "socket" . "api" $api) }}

{{ end }}

<h2>Parameters</h2>

{{ if not .parameters }}

<p>No parameters are declared.</p>

{{ end }}

{{ range .parameters }}

<section class="api-field" data-api-parameter="{{ .name }}">

<h3>

<code>{{ .name }}</code>

<small>{{ .in }}</small>

{{ if .required }}

<small class="api-required">Required</small>

{{ end }}

</h3>

<div class="prose dark:prose-invert">

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) | markdownify }}

</div>

{{ if isset . "schema" }}

{{ partial "api-reference/schema.html" (dict "schema" .schema "api" $api "depth" 0) }}

{{ end }}{{ with .content }}

<pre><code>{{ . | jsonify (dict "indent" " ") }}</code></pre>

{{ end }}{{ with .style }}

<p>Serialization: <code>{{ . }}</code></p>

{{ end }}

</section>

{{ end }}

<h2>Request and responses</h2>

<label

>Media type

<select data-api-media-select>

<option value="">All media types</option>

{{ $media := slice }}{{ range .variants }}

{{ if .media }}

{{ $media = $media | append .media }}

{{ end }}

{{ end }}{{ range ($media | uniq | sort) }}

<option value="{{ . }}">{{ . }}</option>

{{ end }}

</select></label

>

{{ range $i, $v := .variants }}

<section

class="api-variant"

data-api-variant="{{ $v.pointer }}"

data-api-media="{{ $v.media }}"

>

<h3>

<span>{{ $v.direction | humanize }}</span>

{{ with $v.status }}

<code class="api-status">{{ . }}</code>

{{ end }}

</h3>

<div class="prose dark:prose-invert">

{{ partial "api-reference/description.html" (dict "text" $v.description "api" $api) | markdownify }}

</div>

{{ if $v.media }}

<p class="api-media"><code>{{ $v.media }}</code></p>

{{ else }}

<p>No response content is declared.</p>

{{ end }}

{{ with $v.headers }}

<h4>Headers</h4>

{{ range $name,$header := . }}

<div class="api-field">

<code>{{ $name }}</code>

<p>{{ $header.description }}</p>

<pre><code>{{ $header | jsonify (dict "indent" " ") }}</code></pre>

</div>

{{ end }}

{{ end }}

{{ if isset $v "schema" }}

{{ partial "api-reference/schema.html" (dict "schema" $v.schema "api" $api "depth" 0) }}

{{ end }}

{{ if isset $v "itemSchema" }}

<h4>Stream item</h4>

{{ partial "api-reference/schema.html" (dict "schema" $v.itemSchema "api" $api "depth" 0) }}

{{ end }}

{{ range $key := slice "encoding" "itemEncoding" "prefixEncoding" }}

{{ with index $v $key }}

<details>

<summary>

{{ $key }}: content types and part headers

</summary>

<pre><code>{{ . | jsonify (dict "indent" " ") }}</code></pre>

</details>

{{ end }}

{{ end }}

{{ if $v.examples }}

<div data-api-examples>

{{ if gt (len $v.examples) 1 }}

<label

>Example

<select data-api-example-select>

{{ range $j,$ex := $v.examples }}

<option value="{{ $j }}">{{ $ex.name }}</option>

{{ end }}

</select></label

>

{{ end }}{{ range $j,$ex := $v.examples }}

<div data-api-example="{{ $j }}">

<h4>{{ $ex.name }}</h4>

<pre><code>{{ $ex.text }}</code></pre>

</div>

{{ end }}

</div>

{{ end }}

</section>

{{ end }}

<h2>Referenced schemas</h2>

{{ range .references }}

{{ if .url }}

<p><a href="{{ .url }}">{{ .ref }}</a></p>

{{ end }}

{{ end }}

<details>

<summary>Complete operation contract</summary>

<pre><code>{{ .raw | jsonify (dict "indent" " ") }}</code></pre>

</details>

</div>

<aside class="api-request">

<div class="api-request-heading">

<h2>

{{ if .curl }}

Example request

{{ else }}

WebSocket client

{{ end }}

</h2>

{{ if .curl }}<span>Shell</span>{{ end }}

</div>

{{ if .curl }}

<p>

Replace placeholders and supply the required credentials or

request body.

</p>

<pre><code data-api-copy-source>{{ .curl }}</code></pre>

<button type="button" data-api-copy>Copy request</button>

{{ end }}{{ range .curlNotes }}<p>{{ . }}</p>{{ end }}

</aside>

</div>

{{ end }}

{{ end }}

{{ else if eq .Params.view "schema" }}

{{ range $api.schemas }}

{{ if eq .name $.Params.schemaName }}

<p class="api-eyebrow">Schema</p>

<h1>{{ .name }}</h1>

{{ partial "api-reference/schema.html" (dict "schema" .schema "api" $api "depth" 0) }}

{{ end }}

{{ end }}

{{ end }}

{{ end }}

</article>

{{ end }}