The Registry v2 API: The Contract Behind Every Docker Pull and Push
Every time you run `docker pull` or `docker push`, a precisely defined HTTP protocol is quietly at work behind the scenes — the Registry v2 API — and understanding it explains why image distribution is fast, verifiable, and consistent across every registry you'll ever use.
Imagine an international shipping standard that every port in the world agrees to follow — a precise specification for how containers are labeled, how their contents are verified against a manifest, and how a ship can efficiently check which containers it already has on board before requesting only the ones it’s missing. Because every port follows the exact same standard, a shipping company can interact with any port in the world using the same procedures, the same paperwork, and the same verification checks. The Docker Registry v2 API plays exactly this role for container images: a single, precisely defined specification that any registry — Docker Hub, a private company registry, a cloud provider’s registry — can implement, so that the same `docker pull` and `docker push` commands work identically everywhere.
1What Is the Registry v2 API?
Before diving into its mechanics, it helps to understand exactly what problem this API exists to solve.
A Registry Is Just a Specialized HTTP Server
At its core, a Docker registry is a server that stores and serves container images, and the Registry API is the specific set of HTTP endpoints that define how clients — like the Docker CLI — talk to that server to push new images, pull existing ones, list tags, and check what’s already available. The Registry v2 API is the modern, current version of this specification, and it’s what every major registry implementation in active use today speaks.
Why “v2” Matters
The original v1 registry protocol had real limitations around efficiency and verification — most notably, it lacked the strong content-addressable design that makes today’s layer sharing and integrity checking possible. The v2 API was a deliberate redesign that introduced immutable, content-addressed storage as a first-class concept, along with a cleaner, more efficient protocol for handling the layered nature of container images. Today, v1 support has been fully retired across the ecosystem, and v2 is simply “the” registry API.
Think of a specialized courier warehouse that stores packages using a strict rule: every package is labeled with a fingerprint calculated directly from its exact contents, not an arbitrary tracking number someone made up. If two different customers send the exact same package contents, the warehouse recognizes the fingerprint matches something already on the shelf and simply stores one copy, pointing both customers’ records at it. The Registry v2 API works the same way with image layers — content, not arbitrary names, determines identity, which is precisely what makes layer sharing and integrity verification so reliable.
Repository
A named collection of related images in a registry, typically representing one application, identified by a name like myapp/backend.
Manifest
A JSON document describing an image — its layers, its configuration, and how those pieces fit together — which the registry serves as the entry point for pulling an image.
Blob
A single binary piece of data stored by the registry — typically an image layer or a configuration object — identified by the cryptographic digest of its exact contents.
Digest
A cryptographic hash of a blob or manifest’s exact content, used as its permanent, verifiable identifier throughout the v2 API.
2Architecture: The Building Blocks of a Registry
The v2 API organizes everything around a small set of clear, well-defined concepts that combine to represent a complete image.
graph TD
A[Repository - e.g. myapp/backend] --> B[Tag - e.g. latest, v1.2.0]
B --> C[Manifest - JSON descriptor]
C --> D[Config Blob - image metadata]
C --> E[Layer Blob 1]
C --> F[Layer Blob 2]
C --> G[Layer Blob 3]
style C fill:#fef2f2,stroke:#dc2626
Tag
A human-friendly, mutable label (like latest or v2.1.0) that points to a specific manifest at any given moment.
Manifest List / Image Index
A higher-level manifest that points to several platform-specific manifests, enabling a single tag to serve different architectures automatically.
Content-Addressable Storage
The underlying storage principle where every blob’s identity is derived from its own content, making duplicate content automatically deduplicated.
Authentication Service
A typically separate service, referenced by the registry, responsible for issuing time-limited access tokens that authorize specific pull or push operations.
3Internal Working: The Pull Workflow
Walking through exactly what happens, step by step, during a `docker pull` reveals the elegance of the v2 protocol.
sequenceDiagram
participant Client as Docker Client
participant Auth as Auth Service
participant Reg as Registry
Client->>Reg: Request manifest for myapp:latest
Reg-->>Client: 401 Unauthorized, points to Auth Service
Client->>Auth: Request access token
Auth-->>Client: Signed, time-limited token
Client->>Reg: Request manifest again, with token
Reg-->>Client: Manifest JSON (lists config + layer digests)
Client->>Client: Check which layer digests already exist locally
Client->>Reg: Request only the missing layer blobs
Reg-->>Client: Layer blob data
Client->>Client: Verify each blob's digest matches, then assemble image
Why Only Missing Layers Are Downloaded
Because every layer is identified by the digest of its own content, the Docker client can compare the digests listed in a manifest against the digests it already has cached locally, and skip downloading anything that’s already present. This is exactly why pulling a new version of an image you’ve pulled before is often nearly instant — most of the underlying layers are typically unchanged and already sitting on your disk.
Digest Verification: Trust, but Verify
After downloading each blob, the client independently recalculates its digest from the actual received bytes and compares that against the digest the manifest declared. If they don’t match — whether due to corruption, a transmission error, or tampering — the client rejects the blob outright. This gives every single pulled image cryptographic proof that its content is exactly what the registry’s manifest said it should be.
4Internal Working: The Push Workflow
Pushing an image follows a similarly deliberate sequence, designed to avoid re-uploading data the registry may already have.
Client obtains a push-authorized token
Just as with pulling, the client authenticates with the auth service to receive a token specifically scoped to permit pushing to the target repository.
Client checks whether each blob already exists on the registry
Before uploading anything, the client asks the registry whether it already has a blob matching a given digest — if so, that upload can be skipped entirely.
Only missing blobs are uploaded
Each layer or configuration blob the registry doesn’t already have is uploaded individually, again identified by the digest of its own content.
The manifest is uploaded last
Once every referenced blob is confirmed present on the registry, the manifest describing how they fit together is uploaded, effectively finalizing the image.
The tag is updated to point at the new manifest
The human-readable tag is updated last, atomically switching from any previous manifest to the newly pushed one.
Uploading the manifest only after all its referenced blobs are confirmed present prevents a registry from ever ending up with a manifest that points to data it doesn’t actually have — a partial or interrupted push simply leaves an incomplete set of blobs with no manifest referencing them, rather than a broken, half-available image.
5Advantages and Trade-offs
The v2 design brings real, tangible benefits, alongside a few trade-offs worth being aware of.
Advantages
- Content-addressable storage automatically deduplicates identical layers across completely unrelated images
- Cryptographic digest verification guarantees pulled content matches exactly what the registry declared
- Only missing layers need to be transferred, making incremental pulls and pushes fast and bandwidth-efficient
- A single, standardized protocol means the same client works consistently across every compliant registry implementation
- Manifest lists enable one tag to transparently serve the correct image for different CPU architectures
Disadvantages / Trade-offs
- The token-based authentication flow adds real complexity compared to simpler authentication schemes
- Registries must implement correct, careful garbage collection, since deleting a tag doesn’t automatically delete blobs still referenced elsewhere
- Manifest and blob immutability, while good for integrity, means “updating” an image is really always creating and pointing to something new, not editing in place
- Large numbers of small layers can still add per-request overhead, even with efficient incremental transfer
6Security Implications
The Registry v2 API bakes several important security properties directly into its design, though real-world security still depends on how it’s deployed and used.
Because every blob and manifest is identified and verified by a cryptographic digest of its own exact content, tampering with data in transit or at rest is detectable — the client will refuse to accept content that doesn’t match its declared digest.
Rather than granting broad, standing credentials, the v2 API’s authentication model issues short-lived, narrowly scoped tokens for specific operations on specific repositories, limiting what a leaked or intercepted token could actually be used for.
Digest verification confirms an image wasn’t tampered with in transit — it says nothing about whether the image’s original contents were safe or trustworthy in the first place. Image signing and vulnerability scanning are separate, additional practices needed to establish genuine trust in what an image actually contains.
7Registry v1 vs. v2: What Changed
A direct comparison makes clear why the v2 redesign was such a significant improvement.
| Aspect | Registry v1 (Legacy) | Registry v2 |
|---|---|---|
| Content identity | Arbitrary, mutable identifiers | Cryptographic digests of actual content |
| Integrity verification | Limited | Built-in digest verification for every blob |
| Layer deduplication | Inconsistent | Automatic, based on content-addressable storage |
| Multi-architecture support | Not natively designed for it | Native support via manifest lists / image indexes |
| Current status | Retired across the ecosystem | The universal standard in active use today |
8Design Patterns and Anti-patterns
Working effectively with registries over time surfaces some clear best practices and common missteps.
Problem
Relying exclusively on the mutable latest tag to reference images in production deployment configuration.
Why It’s Harmful
Because tags are mutable pointers that can be updated to point at a completely different manifest at any time, deploying by tag alone means you can’t be certain exactly which image content actually got deployed, making rollbacks and audits unreliable.
Correct Approach
Reference images by their immutable content digest in production deployment configuration, using tags primarily as a human-friendly convenience during development.
Problem
Assuming that deleting a tag from a registry immediately frees up all the storage space its underlying layers were using.
Why It’s Harmful
Because blobs are shared across images through content-addressable storage, other images may still reference the same underlying layers even after a tag is deleted, so naive deletion assumptions can lead to unexpected storage costs or, worse, unsafe manual deletion of data still in use.
Correct Approach
Rely on the registry’s proper garbage collection process, which correctly determines whether a blob is still referenced by any remaining manifest before actually removing it.
Problem
An organization needs confidence that the image running in production is exactly the image that was built and tested, with no substitution possible.
Why It Works
Pinning deployments to specific content digests, combined with image signing, creates an unbroken, verifiable chain from the original build all the way to what’s actually running, leaving no room for an untracked substitution along the way.
Correct Approach
Capture the exact digest produced at build time and carry that specific digest through every subsequent deployment step, rather than re-resolving a tag at each stage.
9Monitoring, Logging, and Key Metrics
A registry is critical infrastructure for any team running containers, and it deserves dedicated observability.
Pull and push latency
Tracking how long pull and push operations take helps catch registry performance degradation before it starts slowing down deployments and CI pipelines across the organization.
Authentication failure rate
A spike in authentication failures can indicate misconfigured credentials, an expiring token issue, or a potential unauthorized access attempt worth investigating.
Storage growth and garbage collection effectiveness
Monitoring how registry storage grows over time, and how effectively garbage collection reclaims space from unreferenced blobs, prevents unexpected storage cost surprises.
Digest verification failures
Any occurrence of a digest verification failure on the client side is worth investigating immediately, since it indicates either data corruption or a genuine integrity problem.
10Real-World and Industry Examples
The v2 API’s status as a shared standard is precisely what makes the modern container registry ecosystem work.
Public Registries
Widely used public registries implement the Registry v2 API as their foundation, which is why the exact same Docker client commands work identically whether pulling a public, community-maintained image or an official vendor image.
Private Enterprise Registries
Organizations running their own private registries — whether self-hosted or provided by a cloud vendor — rely on v2 compliance specifically so their existing tooling, CI pipelines, and developer workflows continue working without modification.
Registry Mirroring and Caching
Because the v2 API is standardized and content-addressable, organizations can run local pull-through caches or mirrors of upstream registries, transparently speeding up image pulls across large teams or geographically distributed infrastructure.
11Frequently Asked Questions
Because layers are identified by content digest, if you already have a layer locally from an entirely different image that happens to share identical content, the client recognizes the match and skips downloading it again.
A tag is a human-friendly, mutable label that can be updated to point at different content over time, while a digest is an immutable, cryptographic fingerprint of one specific, exact piece of content that never changes.
No. It guarantees that the content you received matches exactly what the registry declared, protecting against corruption and tampering in transit — but it says nothing about whether that content is free of vulnerabilities or malicious code in the first place.
Because the client checks with the registry which blobs it already has before uploading anything, layers that already exist on the registry — often from a previous version of the same image — are skipped entirely.
No, v1 support has been fully retired across the ecosystem. Every actively maintained registry implementation in use today speaks the v2 API.
Because tags are mutable and can be updated to point at different content at any time, referencing by digest guarantees the exact same, verifiable content is deployed every time, which is essential for reliable rollbacks and audits.
12Summary and Key Takeaways
The Registry v2 API is the quiet standard that makes the entire container ecosystem interoperable — the reason the same `docker pull` and `docker push` commands work identically whether you’re talking to a public registry, a private enterprise one, or a small self-hosted instance. By building content-addressable identity and cryptographic verification directly into its core design, it turns image distribution from a simple file transfer into something with real, checkable guarantees about exactly what you’re getting. Understanding this protocol — manifests, blobs, digests, and the careful choreography of push and pull — demystifies what’s actually happening every time a container image moves across the network.
Key Takeaways
- Content, not arbitrary names, defines identity — every blob and manifest is identified by a cryptographic digest of its own exact content.
- Manifests tie everything together — a manifest describes an image’s configuration and layers, and is the entry point for every pull.
- Only missing data moves across the network — both pulls and pushes skip content the other side already has, based on digest comparison.
- Digest verification protects integrity — clients independently verify every downloaded blob against its declared digest before trusting it.
- Tags are mutable, digests are not — production deployments should pin to digests for reliable, auditable, reproducible deployments.
- Token-based auth narrows access — short-lived, scoped tokens limit what a leaked credential could actually be used for.
- It’s a shared standard — v2 compliance is exactly what lets the same tooling work identically across public, private, and self-hosted registries.