Migrate from Zulu OpenJDK Discovery API to Azul Metadata API
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:
-
https://api.azul.com/zulu/download/community/v1.0/bundles/
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/?availability_types=ca
-
https://api.azul.com/zulu/download/sa/v1-early-access/bundles/
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/?availability_types=sa
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 |
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 |
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 |
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:
-
Get OpenJDK builds with major version 17
https://api.azul.com/zulu/download/community/v1.0/bundles?java-version=17
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages?availability_types=ca&java-version=17
-
Get OpenJDK builds compatible with ARM, 32 bit, soft float (using include fields to verify)
has been replaced by
-
Get latest OpenJDK builds compatible with Alpine Linux (using include fields to verify) https://api.azul.com/zulu/download/community/v1.0/bundles?os=linux-musl&latest=true&include-fields=os,lib_c_type
has been replaced by
Updated Package Detail Endpoint
New metadata endpoint:
Replacement examples:
-
https://api.azul.com/zulu/download/community/v1.0/bundles/{bundle_id}
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/{package_uuid}
-
https://api.azul.com/zulu/download/sa/v1-early-access/bundles/{bundle_id}
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/{package_uuid}
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 |
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 |
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 |
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 |
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:
-
Get OpenJDK bundle with uuid 6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833
https://api.azul.com/zulu/download/community/v1.0/bundles/16088
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833
Updated Package Binary Endpoint
New metadata endpoint:
Replacement examples:
-
https://api.azul.com/zulu/download/community/v1.0/bundles/{bundle_id}/binary
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/{package_uuid}/binary
-
https://api.azul.com/zulu/download/sa/v1-early-access/bundles/{bundle_id}/binary
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/{package_uuid}/binary
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 |
Binary Response
There is no change in the HTTP response. It is a redirect to the package’s download URL.
Example:
-
Download OpenJDK bundle with uuid 6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833
https://api.azul.com/zulu/download/community/v1.0/bundles/16088/binary
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833/binary
Updated Package Signature Binary Endpoint
New metadata endpoint:
Replacement examples:
-
https://api.azul.com/zulu/download/community/v1.0/bundles/{bundle_id}/signature-binary
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/{package_uuid}/signature-binary
-
https://api.azul.com/zulu/download/sa/v1-early-access/bundles/{bundle_id}/signature-binary
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/{package_uuid}/signature-binary
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 |
Response
There is no change in the HTTP response. It is a redirect to the URL that returns a package’s signature.
Example:
-
Download OpenJDK bundle with uuid 6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833
https://api.azul.com/zulu/download/community/v1.0/bundles/16088/signature-binary
has been replaced by
https://api.azul.com/metadata/v1/zulu/packages/6f89cfa2-dd4c-11ea-a8fe-fa163ed8e833/signature-binary
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:
-
Get uuid for package with sha56 hash e043cde3bc0293957985cd612e5eb7a86ffc3df1eaecefbca2b0d0e69107ae71
-
Get uuid for package with md5 hash 19c2609d17f029b9078a84c2c4b1b3bd
https://api.azul.com/metadata/v1/zulu/packages/md5/19c2609d17f029b9078a84c2c4b1b3bd
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
-
Get list of latest OpenJDK major version 17, mac, ARM, JRE no Java FX, dmg:
-
Parse the response to retrieve the
package_uuid
from the first list entry. -
Make request to: