Seperate the notion of artifact, release, and version in the API (v3?)

[bdw429s]

One aspect of the API which is rather confusing is the relationship between version and release. There's too much overlap going on.

Take the following API URL for example:

https://api.adoptopenjdk.net/v2/info/releases/openjdk9?release=jdk-9.0.4%2B11&type=jdk

• Why is the number 9 twice in there?
• Why is the text "jdk" twice in there (thrice actually)?
  • This tells us we're crossing concerns. Please make one part of the API filter on a single thing, not two or three things
• The version portion of the URL is openjdk9 but this has two issues
  • It is more than just the version, it is also the name of the project
  • It isn't even the full version, just the first number
• release portion of the URL is jdk-9.0.4%2B11 but it is mixing several concerns.
  • The type
  • The actual version
  • In some cases, the JVM Implementation
• I'll grant that the release name is perhaps just meant to be a human readable aggregate of information about the release, but without a proper (and full) version identifier, we have no choice but to parse the release name for things programmatically which makes the release name inconsistency a killer.
• I recommend that the openjdkX bit drop the number entirely in favor of a new filter that actually is the version, the full version, and nothing but the version. (See #132 )
• And this brings up a good question-- if the API will never serve anything other than OpenJDK builds, why would the remaining openjdk bit even be necessary at this point? It just seems redundant. ALL requests to the API are for OpenJDK so there's no need to specify that.

An API format that makes more sense would be something like this:

https://api.adoptopenjdk.net/v3/info/releases/?version=9.0.4%2B11&type=jdk

This URL is very straightfoward, contains no duplicate information, and can be built programmatically much more easily than the current v2 format. It simply says:

• Give me info on an OpenJDK release
• Version 9.0.4+11
• Type is JDK

See my related ticket about having proper (and consistent) version support here:
#132

And just to address an organizational hierarchy I've been seeing (and to head off some anticipated replies)-- I get that behind the scenes, at the OpenJDK Project, and at the repo levels, there is a level of separation between major version jumps like openjdk9 and oenjdk10. My recommendation is to stop pushing those implementation details onto the users of our API. The entire API is about OpenJDK, and the version is simply one variable the user can tweak. Don't change endpoints just because there's a different repo involved. To users of the API, it's as simple as wanting:

• OpenJDK (duh!)
  • version X
  • type Y
  • OS Z
  • etc

I think there's some significant good to be had from boiling down the complexities of the OpenJDK Project and simplifying the API to make sense to the end user, not a nod to the underlying infrastructure. I'm seeing a lot of comments from Adopt users indicating their hands are tied and they must pass along the idiosyncrasies of OpenJDK to the user and I disagree with that idea. (Ex: adoptium/temurin-build#674) Make an API that makes sense to humans and translates as necessary to the actual build information behind the scenes.

[supahgreg]

@bdw429s if you're up for it, a working proof-of-concept (e.g. a /v3/info/releases endpoint) might be nice. I think there's definitely interest in improving the API (in multiple regards), so that could help kick things off.

[bdw429s]

I love building APIs, but I don't love Node :) My axe of choice is CFML (a JVM lang) but I'm not sure a CFML-based REST API would be of much interest to Adopt. That and I have no idea what data powers the endpoints behind the scenes. Now, maybe we could flesh out some more specifics like a Swagger spec or something on what the inputs and outputs would be. That sounds fairly useful, but I'd need to do some research on how the nightly endpoints work. So far, I've only needed to care about stable release.

[karianna]

V3 API resolves this.