Proposal: Shortened URL Redirection for Adoptium Downloads

[gdams]

Summary

I propose implementing a new, shorter URL format for Adoptium download links using the domain dl.adoptium.net. This approach simplifies the download URLs and allows us to dynamically redirect them to the corresponding binaries on GitHub releases.

New URL Format

The new URL format would be https://dl.adoptium.net/{major_version}/{openjdk_version}/{file_name}

For example:

https://dl.adoptium.net/17/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

redirects to:

https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

Implementation

I propose using Cloudflare Redirect Rules to handle the dynamic redirection. These rules allow us to capture different versions and file extensions, automatically redirecting users to the appropriate GitHub release page. Once implemented we would need to update the API to return download URLs using this URL shortner rather than the original github.com release link. Changing the API alone should capture nearly all use-cases.

Benefits

1. Shorter, more user-friendly URLs: The dl.adoptium.net domain is shorter and easier to share, improving user experience.
2. Telemetry: Using our own domain for downloads provides opportunities for gathering better telemetry data, allowing us to track download patterns and volumes more effectively.
3. Flexibility: If we decide to move away from GitHub releases in the future, we can easily update the redirection rules without breaking existing download links.

I have left a rule running in Cloudflare so I encourage people to try out the new URL and provide feedback!

[tellison]

dl.adoptium.net is not much shorter than api.adoptium.net or am I missing something?

Creating a new schema around "{major_version}/{openjdk_version}/{file_name}" may be something to roll into the current scheme, but also has the potential to cause confusion by having two ways to do things.

FWIW I've not seen a pushback to the length of the current URLs.

[sxa]

I would be slightly concerned that we might end up discouraging the use of the API, or giving mixed messages, by making these URLs available. We have historically actively steered end users towards the API for such things and avoid advocating going directly to the endpoints, and while the API can feel certainly feel a bit more complex than it perhaps should (I often point people to https://adoptium.net/en-GB/blog/2023/08/early-access-builds/ for some simple JDK download examples - the ones that were on the front of the API site are no longer there) that is the path we have chosen for such automation up to now.

In terms of Tim's comment about length I guess we're comparing:

• https://api.adoptium.net/v3/binary/version/jdk-17.0.12%2B7/linux/x64/jdk/hotspot/normal/adoptium
• https://dl.adoptium.net/21/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz
• https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

On the telemetry point, can we not get that from the current API?

And similarly from a flexibility perspective, we would cover that from the API too if we moved to an alternate hosting platform so I'm not yet convinced that this is compelling from that perspective.

[tellison]

[...] about length I guess we're comparing:

• https://api.adoptium.net/v3/binary/version/jdk-17.0.12%2B7/linux/x64/jdk/hotspot/normal/adoptium
• https://dl.adoptium.net/21/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz
• https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

I hope we can withdraw the github.com URL from the comparison, since it doesn't meet the objective of isolating the download URL from the underlying storage system.

If we do need/wish to shorten the URL, how about we give Temurin JDK defaults to the image_type, jvm_impl, heap_size, and vendor parameters; so that the current URL

https://api.adoptium.net/v3/binary/version/jdk-17.0.12%2B7/linux/x64/jdk/hotspot/normal/adoptium

becomes

https://api.adoptium.net/v3/binary/version/jdk-17.0.12%2B7/linux/x64

(I believe there is still value in maintaining the API version element)

[gdams]

And similarly from a flexibility perspective, we would cover that from the API too if we moved to an alternate hosting platform so I'm not yet convinced that this is compelling from that perspective.

I think the big difference is that this would rely on someone to check the API for updates as opposed to being able to dynamically switch the backend and keep URLs valid. Here's an example (all hypothetical ofcourse)

We decide to move from GitHub Releases to Artifactory for our binary releases:

As things stand we could update the API to return the new links so the website would continue to work and many users who correctly use the API would receive the updated link and hopefully be able to download it with little to no changes in their code. But.... many users might have used templating logic to generate the download URLs or they might have gone to the website, clicked the latest version and then copied the source URL into their build CI - for all these users they are now broken.

I'm not suggesting a replacement of the API here (I think that would be very counterproductive, rather I'm thinking of ways that we can further reduce the risk.

[tellison]

many users might have used templating logic to generate the download URLs or they might have gone to the website, clicked the latest version and then copied the source URL into their build CI

So if I understand correctly, your proposal is that we continue to promote the current API, but serve up the dl URL as the redirected location? i.e.

GET /v3/binary/version/jdk-17.0.12%2B7/linux/x64/jdk/hotspot/normal/adoptium

instead of currently returning a 307 with location: https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

it would return a 307 with dl.adoptium.net/21/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

Is that correct? I'm asking because the original post refers to making user friendly download URLs for sharing, and I'm not sure that is the purpose of those redirected locations. IMHO we would end up with effectively two api routes for users.

[gdams]

instead of currently returning a 307 with location: https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

it would return a 307 with dl.adoptium.net/21/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

That's exactly the idea, perhaps the wording isn't very clear, it's simply to remove our dependency on https://github.com/adoptium/temurin{x}-binaries/releases/download/ which could disappear one day. It would also give us the ability to switch over to a backup in the event of a GitHub outage.

[tellison]

This was discussed at the PMC meeting on Oct 9th as minuted.