Visit Azul.com Support

Migrate from Zulu OpenJDK Discovery API to Azul Metadata API

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

Since the beginning of 2023, Azul promotes the Metadata API in favor of the Discovery API. This new API is able to provide more information about the various builds and products of Azul, while the Discovery API only provided info about Azul Zulu Builds of OpenJDK.

This document provides an overview to migrate to the new Metadata API.

URL Changes

Base URL of the new Metadata API is api.azul.com/metadata/v1, for instance:

This replaces these base URLs of the Zulu Discovery API:

  • api.azul.com/zulu/download/community/v1.0

  • api.azul.com/zulu/download/sa/v1-early-access

  • api.azul.com/zulu/download/azure-only/v1.0

The Metadata API supports both community availability (CA) and subscriber availability (SA) packages of Azul Platform Core in a single API. Since no new Azure-only bundles and packages are being published, API support for Azure-only data is limited. The underlying metadata is the same, and the Metadata API endpoints are very similar, so users can easily migrate to this new Metadata API.

Overview of changes

  • Where the Zulu Discovery APIs use the term bundle, the Metadata API uses the term package.

  • While the Zulu Discovery APIs have different APIs for supported and free packages, the new Metadata API uses availability-type filters to determine if a package is freely available or not. All customer packages require an API token to download, similar to the token used by the old api.azul.com/zulu/download/sa/v1-early-access.

  • Packages previously available from api.azul.com/zulu/download/community/v1.0 should use the filter availability-type=ca.

  • Packages previously available from api.azul.com/zulu/download/sa/v1-early-access should use the filter availability-type=sa and must authenticate with an API token.

    Customers with a support contract can contact Azul Support ([email protected]) to get an API token.

  • Azure-only has been deprecated, since no new azure only packages are being published.

  • The Metadata API has dropped support for /bundles/latest* and /bundles/sha256* endpoints and added support for retrieving a package’s UUID using a SHA256 hash or MD5 hash. See below for examples of how to replace requests using the dropped endpoints.

Updated Package List Endpoint

New metadata endpoint:

Replacement examples:

Request Filter Differences

Filters for the Metadata API list-endpoint work in much the same way as those for the Zulu Discovery API, however, a few filters have been combined in to a single filter. The differences are listed in this table.

Zulu Discovery API

Metadata API

Description

Filter

Filter

Name

Value(s)

Name

Value(s)

jdk_version

dot separated string, ie 17.0.1

java_version

dot separated string, ie 17.0.1

Filter name change only.

zulu_version

dot separated string, ie 8.68.0.21

distro_version

dot separated string, ie 8.68.0.21

Filter name change only.

os

linux, linux_musl, macos, windows, solaris, qnx

os

linux, linux_musl, linux_glibc, macos, windows,solaris, qnx

Filter value change. + The Metadata API OS filter combines OS and lib-c attributes. This mainly effects Linux filters, the linux filter now returns both linux-musl and linux-glibc packages. Use linux-glibc filter instead of linux to get only linux glib-c packages.

arch

x86, arm, mips, ppc, sparcv9

arch

x86, x64, amd64, i686, arm, aarch64, aarch32, aarch32sf, aarch32hf, ppc, ppc64, ppc32, ppc32hf, ppc32spe, sparc, sparc64, sparc32, sparcv9, sparcv9-64, sparcv9-32

Filter value change. + The Metadata API combines arch, hw-bitness and abi filters, and supports values used in the package names.

hw_bitness

64, 32

n/a

n/a

The filter was dropped in the Metadata API, use the arch filter instead.

abi

soft_float, hard_float

n/a

n/a

The filter was dropped in the Metadata API, use the arch filter instead.

ext

deb, rpm, dmg, tar.gz, zip, cab, msi

archive_type

deb, rpm, dmg, tar.gz, zip, cab, msi

Filter name change only.

bundle_type

jdk, jre

java_package_type

jdk, jre

Filter name change only.

javafx

true, false

javafx_bundled

true, false

Filter name change only.

release_status

ga, ea, both

release_status

ga, ea, both

No change.

support_term

lts, mts, sts

support_term

lts, mts, sts

No change.

features

cp3, fx, headful, headfull, headless, jdk

java_package_features

cp1, cp2, cp3, headful, headfull, headless, fx, jdk

Filter name change and additional filter values.

release_type

CPU, PSU

release_type

CPU, PSU

No change.

include_fields

any bundle detail key

include_fields

any package detail key

Filter value changes due to different package detail keys.

latest

true, false

latest

true, false

No change.

n/a

n/a

availability_types

list with value(s): ca, sa

Filter added in the Metadata API.

n/a

n/a

certifications

tck, none

Filter added in the Metadata API.

n/a

n/a

page

integer

Filter added in the Metadata API.

n/a

n/a

page_size

integer

Filter added in the Metadata API.

Response Differences

The Metadata API data are paginated and return 100 items by default, with a max page size of 1000, depending on the list filters. Multiple HTTP requests may be needed to retrieve a full list of packages. Data are sorted, with the newest packages being returned first.

Zulu Discovery API

Metadata API

Description

Attribute

Attribute

Name

Value type

Name

Value type

id

integer

package_uuid

string

The package_uuid is used to identify packages.

java_version

array of integers

java_version

array of integers

No change.

jdk_version

array of integers

n/a

n/a

Is dropped in the Metadata API, use java_version.

openjdk_build_number

integer

openjdk_build_number

integer

No change.

name

string

name

string

No change.

url

string

download_url

string

Attribute name change only.

zulu_version

array of integers

distro_version

array of integers

Attribute name change only.

n/a

n/a

latest

true, false

Added in the Metadata API list return data.

n/a

n/a

availability_type

ca, sa

Added in the Metadata API list return data.

n/a

n/a

product

zulu, zulu_prime

Added in the Metadata API list return data.

Examples:

Updated Package Detail Endpoint

New metadata endpoint:

Replacement examples:

Request Parameter Differences

Parameters for the Metadata API detail endpoint use a package UUID instead of a bundle ID. Unlike the Zulu download bundle_id, the package_uuid never changes, and can always be used to identifying a package.

Zulu Discovery API

Metadata API

Description

Parameter

Parameter

Name

Value type

Name

Value type

bundle_id

integer

package_uuid

string

Value that uniquely identifies a package is now a UUID string, for example 6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833.

Response Differences

Zulu Discovery API

Metadata API

Description

Attribute

Attribute

Name

Value type

Name

Value type

bundle_uuid

string

package_uuid

string

Attribute name change + NOTE: package_uuid is used as the primary unique identifier.

id

integer

n/a

n/a

Attribute dropped in the Metadata API, use package_uuid to identify the package.

name

string

name

string

No change.

md5_hash

string

md5_hash

string

No change.

sha256_hash

string

sha256_hash

string

No change.

last_modified

date string

last_modified

date string

No change.

url

string

download_url

string

Attribute name change only.

java_version

array of integers

java_version

array of integers

No change.

jdk_version

array of integers

n/a

n/a

Dropped in the Metadata API, use java_version.

openjdk_build_number

integer

openjdk_build_number

integer

No change.

bundle_type

jdk, jre

java_package_type

jdk, jre

Attribute name change only.

javafx

true, false

javafx_bundled

true, false

Attribute name change only.

features

cp3, fx, headfull, headless, jdk

java_package_features

cp1, cp2, cp3, headfull, headless, fx, jdk

Attribute name change and additional values.

release_type

CPU, PSU

release_type

CPU, PSU

No change.

os

linux, linux_musl, macos, windows, solaris, qnx

os

linux, macos, windows, solaris, qnx

Attribute value changes, the Metadata API OS value contains no lib-c info, use lib_c_type to determine linux_musl.

n/a

n/a

lib_c_type

glibc, uclibc, musl

Added in the Metadata API.

cpu_gen

list containing value(s): v5, v6k/v6kz, v6t2, v7, v8

cpu_gen

list containing value(s): v5, v6k/v6kz, v6t2, v7, v8

No change.

arch

arm, x86, mips, ppc, sparcv9, sparc

arch

arm, x86, mips, ppc, sparcv9, sparc

No change.

hw_bitness

32, 64

hw_bitness

32, 64

No change.

abi

soft_float, hard_float, spe

abi

soft_float, hard_float, spe

No change.

ext

deb, rpm, dmg, tar.gz, zip, cab, msi

archive_type

deb, rpm, dmg, tar.gz, zip, cab, msi

Attribute name change only.

release_status

ga, ea, both

release_status

ga, ea, both

No change.

support_term

lts, mts, sts

support_term

lts, mts, sts

No change.

latest

true, false

latest

true, false

No change.

size

integer

size

integer

No change.

zulu_version

array of integers

distro_version

array of integers

Attribute name change only.

signatures

list of objects

signatures

list of objects

No change.

n/a

n/a

build_date

date string

Added in the Metadata API.

n/a

n/a

product

zulu, zulu_prime

Added in the Metadata API.

n/a

n/a

availability_type

ca, sa

Added in the Metadata API.

n/a

n/a

certifications

null or list containing value(s): tck, aqavit

Added in the Metadata API.

Example:

Updated Package Binary Endpoint

New metadata endpoint:

Replacement examples:

Request Parameter Differences

The parameter for the Metadata API package binary endpoint uses a package UUID instead of a bundle ID. Unlike the Zulu download bundle_id, the package_uuid never changes and can always be used to identify and download a package.

Zulu Discovery API

Metadata API

Description

Parameter

Parameter

Name

Value type

Name

Value type

bundle_id

integer

package_uuid

string

Value that uniquely identifies a package is now a UUID string, for example 6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833.

Binary Response

There is no change in the HTTP response. It is a redirect to the package’s download URL.

Example:

Updated Package Signature Binary Endpoint

New metadata endpoint:

Replacement examples:

Request Parameter Differences

The parameter for the Metadata API signature binary endpoint uses a package UUID instead of a bundle ID. Unlike the Zulu download bundle_id, the package_uuid never changes and can always be used to identify and download a package.

Zulu Discovery API

Metadata API

Description

Parameter

Parameter

Name

Value type

Name

Value type

bundle_id

integer

package_uuid

string

Value that uniquely identifies a package is now a UUID string, for example 6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833.

Response

There is no change in the HTTP response. It is a redirect to the URL that returns a package’s signature.

Example:

New Get UUID Using Hash Endpoint

New metadata endpoint:

Request Parameter Details

Metadata API

Description

Parameter

Name

Value type

hash-type

sha256 or md5

Type of hash

hash-value

string

MD5 or SHA256 hash value.

Response

Response JSON

Description

Key

Value Type or Value

package_uuid

string

Identifier for the package.

product

zulu or zulu_prime

Product for the package UUID.

Examples:

Upgrading Deprecated Endpoints

Deprecated endpoints that are no longer available in the Metadata API:

  • /bundles/latest

  • /bundles/latest/binary

  • /bundles/sha256/<sha256checksum>

  • /bundles/sha256/<sha256checksum>/binary

These endpoints can be replaced by using the new packages-endpoint, following these examples.

Get Latest Version

  1. Get list of latest OpenJDK major version 17, mac, ARM, JRE no Java FX, dmg:

    https://api.azul.com/metadata/v1/zulu/packages?availability_types=ca&java-version=17&os=macos&arch=arm&java-package-type=JRE&javafx-bundled=false&archive-type=dmg&latest=true

  2. Parse the response to retrieve the package_uuid from the first list entry.

  3. Make request to:

Get By Checksum

  1. Get uuid for package with sha256 hash e043cde3bc0293957985cd612e5eb7a86ffc3df1eaecefbca2b0d0e69107ae71:

    https://api.azul.com/metadata/v1/zulu/packages/sha256/e043cde3bc0293957985cd612e5eb7a86ffc3df1eaecefbca2b0d0e69107ae71

  2. Parse response to retrieve the package_uuid.

  3. Make request to: