The Adoptium API V3 is a Kotlin application (fronted by Swagger and OpenAPI) which makes calls via the GitHub API in order to retrieve Adoptium binaries and metadata.
Since the GitHub API is rate limited we use MongoDB as a caching mechanism.
There are two main branches in the project:
mainproduction
All contributions should be made by forking the project and raising a pull request (PR) against the main branch.
The main branch represents the current live state of the Staging environment.
The production branch represents the current live state of the Production environment.
For more details related to deployment of the API, see the deployment section of this guide.
Java 17 is a requirement to build the project.
If you want to use the updater tool to add entries into the database, you need to generate a github token, which can be done here. It doesn't need any specific permissions. Once you have a token generated, create a file at ~/.adopt_api/token.properties and type token=your-token-here
The production server uses mongodb to store data, however you can also use Fongo. If you would like to install mongodb and are on mac, I used this guide which utilizes homebrew. You can also install mongo which is a command-line tool that gives you access to your mongodb, allowing you to manually search through the database.
Maven is used to build the project.
We use the Maven Wrapper (mvnw) to ensure that there's a consistent, repeatable build.
The POM File is the place to start.
NOTE: We use a multi-module project structure. The root level Maven POM contains the majority of the configuration that the children inherit from.
Builds can be targeted to build for Adoptium or AdoptOpenJDK, these are chosen by activating either the adoptium
or adoptopenjdk profiles.
To perform a full build and test you run the following:
./mvnw clean install -Padoptium
If you wish to view all the Maven reporting about the project then after running the above you can run the following:
./mvnw site -Padoptium
WARN: ./mvnw clean install site -Padoptium does not work at time of writing due to an order of operations problem
If you wish to produce an AdoptOpenJDK ecosystem build, use -Padoptopenjdk i.e.
./mvnw clean install -Padoptopenjdk
For convenience, you can build the API components with Docker and docker-compose.
docker-compose buildUsing a multi-stage Dockerfile build, a Docker image is created that supports running both the updater and the front-end.
The docker-compose.yml defines a service for each component, as well a dependency on MongoDB, allowing you to spin up the full stack required for the API.
You just need to provide your GitHub access token as an environment variable and run docker-compose up. For example:
export GITHUB_TOKEN=your-personal-github-token
docker-compose upYou will need to wait the updater to complete its first full run before the API is usable. There is currently no persistence between runs.
The front-end app will be available at http://localhost:8080.
You can connect to the MongoDB instance using your Mongo client at mongodb://localhost:27017.
The project applies the ktlint linter to provide an opinionated set of rules that reflect the official Kotlin code style.
ktlint is configured in the top-level Maven POM and executed during the validate phase of the Maven life-cycle.
Refer to ktlint's docs for more info.
WARN This API is critical to the success of Adoptium therefore it is essential that tests are provided for all new functionality.
Code coverage metrics are collected using JaCoCo and configured via a plugin in the top-level Maven POM.
There is a GitHub Action file which the CI system in GitHub uses to build and test a Pull Request.
NOTE: Please update the dependencies in this file if you have changed the versions of:
- The JDK
- openapi-generator-maven-plugin
We use Swagger to document the API. The Swagger documentation can be viewed at: swagger-ui. The Open API definition for this can be viewed at openapi.
You can choose to deploy this API where you wish, for Adoptium we use Continuous Deployment.
For Adoptium, this API deploys to Microsoft Azure.
The production branch is synchronized with main (via a pull request that applies all outstanding commits from main to production) to perform a release of the latest API changes to the Production environment.
A build and deploy then happens as governed by the Build Docker and Publish files.
For AdoptOpenJDK, this API deploys to Red Hat OpenShift and is front ended by Cloudflare as a CDN.
The production branch is synchronized with main (via a pull request that applies all outstanding commits from main to production) to perform a release of the latest API changes to the Production OpenShift environment.
A build then happens in OpenShift as governed by the Source To Image (s2i) Assembly file file.
The Adoptium API V3 is a Kotlin application (fronted by Swagger and OpenAPI) which makes calls via the GitHub API in order to retrieve Adoptium binaries and metadata.
Since the GitHub API is rate limited we use MongoDB as a caching mechanism.
See Code Structure doc for more details.
For any significant project or architectural changes we use Architecture Decision Records (ADRs) to capture them.
We manage ADRs using adr-tools in the docs/adr directory.
In this section we list some common tasks and where to start.
If you need to add/edit/remove a supported version string then you need to update the VersionParser and its corresponding VersionParserTest.
You'll need to start at the Platforms JSON and Variants JSON.