Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:


November Discount Launch 2022 – TEMP TOP (NPI)
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:


Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

1. Overview

In this tutorial, we'll explore how to list images in a remote Docker registry and how to fetch tags for an image.

This is useful for finding out what versions of a particular image are available in a registry and deciding which one to use.

2. Docker Registry API

A Docker registry provides an API to interact with the registry. This API contains the various endpoints used in the background by the Docker CLI to perform various tasks like pulling, pushing, and tagging images.

We can also use these endpoints directly to interact with a registry without using the Docker CLI.

Let's look at the format of an endpoint of the registry API:


Let's examine the different components of this endpoint:

  • API versionthe version of the API. For example, the current version is v2.
  • Repository(image) nameThe name of the image. The name also can contain a path separated by slashes if it is a nested repository. For example, /ubuntu/nginx or /redis.
  • ResourceThe subdivision of the API we want to interact with. For example, manifests will work with manifests of a particular image.
  • Parameters – These are optional parameters that can be used to further refine the operation. For example, manifests/latest will fetch the manifest for the latest tag.

Based on the above rules, below is a concrete example of an endpoint:

GET /v2/ubuntu/nginx/manifests/latest

3. Docker Registry API V2

At the time of writing, V2 is the current version of the Registry API. Let's explore how to use it to list images and tags from a remote registry.

Let's assume we have a registry deployed at the URL https://my-registry.io. We'll use curl to execute the HTTP requests.

3.1. Listing Images

To list images in a registry, we can use the _/catalog endpoint:

$ curl -X GET my-registry.io/v2/_catalog

We should note that authentication may be required to access certain repositories if it has been enabled. In such cases, we can pass in the username and password as parameters to the curl command using the -u option.

$ curl -u user:password -X GET my-registry.io/v2/_catalog 

3.2. Paginated Listing Images

Sometimes, a registry will have a large number of images. In such cases, we can add an n=<number of results> parameter to the _/catalog endpoint to get a paginated response:

$ curl -X GET my-registry.io/v2/_catalog?n=1

The response contains only the first image now.

We can use the response to the first request to get the next page of results. This needs two changes to the curl command:

  • A last parameter to the _/catalog endpoint containing the last image name returned in the previous request.
  • A header linking the new request to the previous one. The header has the format below:
Link: <my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"

The brackets around the URL are required. The URL is the same as the URL of the new request. A rel=”next” header indicates that the new request is a continuation of the previous one as per RFC 5988.

So let's make the next request:

$ curl -H 'Link: <my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"' -X GET "my-registry.io/v2/_catalog?n=1&last=centos"

The response returns the next page of results containing one image.

3.3. Listing Tags

To list the tags of an image, we can use the /tags/list endpoint:

$ curl -X GET my-registry.io/v2/ubuntu/tags/list

The response contains the name of the image and an array of the tags associated with it.

We can also use pagination with the same rules as we saw for image listing.

4. Docker Registry API V1

Registry API v1 was deprecated in Docker 17.06 and removed in Docker 17.12. However, if we come across a registry hosted before the deprecation, we can use the v1 API. Let's explore how our requests change in this case.

4.1. Listing Images

There is no direct endpoint to list images in v1. Instead, we can use the docker search command to search for images containing a given string:

$ docker search my-registry.io/centos

This returns a list of images that contain the string “centos” in their name or description.

If we do not specify the registry, the search will be performed in the default registry. The default repository is the Docker Hub repository.

For example, the below image shows the output when we search for the term “ubuntu” without specifying any repository.

Docker search ubuntu command run in a terminal and results displaying all the images matching the search query

4.2. Listing Tags

The method to list tags is similar to the v2 API. However, the output is different in this case:

$ curl -X GET https://registry.hub.docker.com/v1/repositories/baeldung/mesos-marathon-demo/tags
[{"layer": "", "name": "32"}, {"layer": "", "name": "33"}, {"layer": "", "name": "34"}]

As we can see, instead of a single array of tags, we have an array of objects. Each object includes the name of the tag and the layer ID of the image.

If needed, we can convert the response to an array. To do so, let's pipe the output into the jq command and parse the JSON:

$ curl -s GET https://registry.hub.docker.com/v1/repositories/baeldung/mesos-marathon-demo/tags | jq -r '[.[].name]'

Let's understand the jq command and expressions used here:

  • The -r flag returns the output as raw text.
  • The expression .[].name returns the name property from each object from the curl output.
  • The square brackets [] around the expression indicate that we want to collect the output in an array.

Finally, the -s flag used with the curl command is required to suppress the progress bar output.

5. Conclusion

In this article, we've explored how to use the Docker Registry API to list images and tags in a remote registry.

We also looked at how to send paginated requests for images and tags and how to parse JSON responses.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:


Generic footer banner
Comments are closed on this article!