[EXPERIMENTAL] MicroBadger Metadata API for Docker Hub Images
The Microbadger Metadata API is a simple API that lets you query the build-time labels for any Docker Hub public image.
A full description of the API is available on our website, but fundamentally
- You call our API with the namespace/name of the image you want to query. Here is an example for one of our public Microscaling images:
GET https://api.microbadger.com/v1/images/microscaling/microscaling
- The JSON response will contain all the labels for every version of that microscaling/microscaling public image (see our api 1-pager for the response, which is a bit voluminous to include here).
Official Images
You can also query an official image using the ‘library’ namespace. For example, query the Alpine official image
GET https://api.microbadger.com/v1/images/library/alpine
Or the Ubuntu official image
GET https://api.microbadger.com/v1/images/library/ubuntu
Note all of the returned information comes from the public image itself on Docker Hub APART from the webHookURL. webHookURL is an example of external, third-party metadata that Microbadger adds to the returned JSON. The image author can use webhookURL to automatically notify Microbadger about changes to their image.
What Do We Do With This API?
- Our own Microbadger service uses the Microbadger Metadata API to display metadata about public images on Docker Hub.
- Internally, our home-grown operational tools need the ability to view build-time metadata for our container images. We use the Microbadger Metadata API for that too.
Why Did We Build an API?
We’re big fans of build and run-time metadata for Docker container images.
We believe build-time metadata should be used to communicate unchanging image information such as what its source code is, what license it’s under or what constraints apply to it (like where it can be run).
We believe metadata and metadata conventions like label-schema will be vital to a new wave of powerful operational tools above the orchestration layer.
You can already build Labels into your images straightforwardly via the Dockerfile.
The issues arise when third party operational tools want to read container labels. Some orchestrators don’t let operational tools sitting above the orchestrator easily read Docker Labels. For example, you can’t read labels through the Kubernetes API. This gave us a problem.
- We use labels a lot.
- We use Kubernetes as our orchestrator and we write our own operational tools that sit above Kubernetes and interact with our running pods and containers via the Kubernetes API.
- The Kubernetes API doesn’t expose the Docker Labels we need.
So, we built our own API for that purpose, which queries the image’s registry for this information. In future we’ll add support for more registries.
Note, it has been proposed that an image should be able read its own labels via introspection. We like this idea but it’s not yet available officially in Docker (not merged in) and doesn’t address our 3rd party issue.
Want to know more about what our operational tools do with the metadata? Coming soon!!!
If you’ve read this far and liked reading, then consider pressing the like button. My understanding is that is what the button is for, and it’s a shame to waste it.
Check out MicroBadger to explore image metadata, and follow Microscaling Systems on Twitter.
