Using Azul Metadata API for Zulu

Table of Contents

About the API
Searching a Zulu Version
- Download Zulu
- Data Model
Authentication for Subscriber Availability Builds
- Authenticate in Swagger
- Authenticate in curl

Need help?

Schedule a consultation with an Azul performance expert.

This section explains how to use the Azul Metadata API.

Note	Please check out "Transition from Zulu OpenJDK Discovery API to Azul Metadata API" if you used the Zulu Discovery API (`api.azul.com/zulu/download`) in the past and want to migrate to this new Azul Metadata API (`api.azul.com/metadata/v1`).

About the API

The Azul Metadata API is a free utility for viewing metadata and downloading Azul Zulu Builds of OpenJDK. Documentation on API endpoints can be found on api.azul.com/metadata/v1/docs/swagger. It can be used without any authentication and gives you access to the Community Availability (CA) Zulu Builds of OpenJDK that are free to download and use.

Azul Customers can also use the Metadata API to get access to the Subscriber Availability (SA) Zulu Builds of OpenJDK that are tested, certified, and commercially supported. See Authentication for Subscriber Availability Builds below for more info.

Via the Swagger UI, the API can be called to try the various APIs and filtering options, and also presents you with the CURL command to get the same results through the terminal.

Searching a Zulu Version

Note	This is just an example at the time of the document being written. You may see a different output depending on the currently available Java versions.

For instance, to find the Zulu downloads with the following criteria:

java_version: 21
os: macos
arch: arm
javafx_bundled: `true

the following CURL command is returned:

 curl -X GET \
  "https://api.azul.com/metadata/v1/zulu/packages/?java_version=21&os=macos&arch=arm&java_package_type=jdk&javafx_bundled=true&release_status=ga&availability_types=CA&certifications=tck&page=1&page_size=100" \
  -H "accept: application/json"

Note	The value for `page_size` can not exceed `1000`.

This returns the following result:

 [
  {
    "availability_type": "CA",
    "distro_version": [
      21,
      36,
      17,
      0
    ],
    "download_url": "https://cdn.azul.com/zulu/bin/zulu21.36.17-ca-fx-jdk21.0.4-macosx_aarch64.zip",
    "java_version": [
      21,
      0,
      4
    ],
    "latest": true,
    "name": "zulu21.36.17-ca-fx-jdk21.0.4-macosx_aarch64.zip",
    "openjdk_build_number": 7,
    "package_uuid": "2385ab1d-b206-4797-8557-eb202e1042d1",
    "product": "zulu"
  },
  ...
]

Note

The latest value in this result, and the 'latest' filter that can be used in the search API, are related to the most recent build that matches the query parameters. This means, depending on the other search criteria that you are using, that the build indicated as latest is specific to the criteria, and not always the most recent build of a specific version.

Download Zulu

The returned data includes a download_url field with a direct link to the download file of the Zulu version. For SA builds, this URL is a signed link with an expiration period. Note that the domain or hostname serving the download URLs, as well as the format of the signed URL parameters (including the expiration), may change without notice, as these details are not part of the Metadata API’s core functionality.

In case of the previous example:

 "download_url": "https://cdn.azul.com/zulu/bin/zulu21.36.17-ca-fx-jdk21.0.4-macosx_aarch64.zip"

Note	Packages retrieved with the filter `availability-type=sa` can only be downloaded by authenticating with an API token. Customers with a support contract can contact Azul Support ([email protected]) to get such a token.

Data Model

The Swagger UI also provides more info about the JSON data model that is returned by the API and can be opened to learn more about all the fields.

Authentication for Subscriber Availability Builds

To use the API for Subscriber Availability (SA) Zulu Builds of OpenJDK, a Bearer Authentication Token is needed. Azul Customers can request such a token from [email protected].

Authenticate in Swagger

Click on the Authorize button.
Fill in your token in the Value field and click the Authorize button.
You can now use the Zulu Swagger APIs and use the availability_types filter with sa.

Authenticate in curl

The following example uses the same criteria to search for Zulu 21 as used above, except the availability_types is changed to SA and the authorization header is added.

 curl -X GET \
  "https://api.azul.com/metadata/v1/zulu/packages/?java_version=21&os=macos&arch=arm&java_package_type=jdk&javafx_bundled=true&release_status=ga&availability_types=SA&certifications=tck&page=1&page_size=100" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

Result without token:

 {"code":403,"message":"not authorized, token with package_zulu_read permissions required","status":"Forbidden"}

Result with token:

 [{"availability_type":"SA","distro_version":[21,38,22,0],"download_url":...}]