Upcoming multi API version support in the STACKIT Java SDK

[rubenhoenle]

As of now every of the SDK modules in the STACKIT Java SDK only supports one API version, usually the latest GA version (e.g. for IaaS it's currently v2).

This means as a developer using the STACKIT Java SDK you didn't have any chance to take control of which API version you're using. Furthermore our SDK didn't include support for alpha API versions in the past.

Since we wanted to provide you with an SDK for all available API versions of the STACKIT services, our SDK structure will undergo some significant changes as you can see below.

From now on there will be seperate packages named after the API versions (e.g. v2api, v3alpha1api, ...) in each SDK module. This way you as a developer will have full control which API version you want to use within your application. Since also all alpha and beta API versions will be included in the SDK from now on, you'll gain access to new experimental API features within the STACKIT SDK.

Warning

Since the STACKIT Java SDK is still in beta the old SDK structure will be entirely removed. This means a breaking change for you.

Note the migration guide below which shows how you can migrate to the new SDK structure.

Old Java SDK structure

📁 stackit-sdk-java
├── 📄 LICENSE.md
├── 📄 README.md
├── 📄 CHANGELOG.md
├── 📄 build.gradle
├── 📄 buildSrc
├── 📁 core
│   ├── 📄 CHANGELOG.md
│   ├── 📄 VERSION
│   ├── 📄 build.gradle
│   └── 📁 src
│       ├── 📁 main
│       │   └── 📁 java
│       │       └── 📁 cloud
│       │           └── 📁 stackit
│       │               └── 📁 sdk
│       │                   └── 📁 core
│       │                       ├── 📄 KeyFlowAuthenticator.java
│       │                       ├── 📄 KeyFlowInterceptor.java
│       │                       ├── 📁 auth
│       │                       └── ...
│       └── 📁 test
├── 📁 gradle
├── 📄 gradlew
├── 📄 gradlew.bat
├── 📁 services
│   ├── 📁 iaas
│   │   ├── 📄 CHANGELOG.md
│   │   ├── 📄 README.md
│   │   ├── 📄 VERSION
│   │   ├── 📄 build.gradle
│   │   └── 📁 src
│   │       ├── 📁 main
│   │       │   └── 📁 java
│   │       │       └── 📁 cloud
│   │       │           └── 📁 stackit
│   │       │               └── 📁 sdk
│   │       │                   └── 📁 iaas
│   │       │                       ├── 📄 ApiCallback.java
│   │       │                       ├── 📄 ApiClient.java
│   │       │                       ├── ...
│   │       │                       ├── 📁 api
│   │       │                       │   ├── 📄 DefaultApi.java
│   │       │                       │   └── 📄 IaasApi.java
│   │       │                       └── 📁 model
│   │       │                           ├── 📄 Server.java
│   │       │                           └── 📄 Volume.java
│   │       └── 📁 test
│   └── 📁 sfs
│       ├── 📄 CHANGELOG.md
│       ├── 📄 README.md
│       ├── 📄 VERSION
│       ├── 📄 build.gradle
│       └── 📁 src
│           ├── 📁 main
│           │   └── 📁 java
│           │       └── 📁 cloud
│           │           └── 📁 stackit
│           │               └── 📁 sdk
│           │                   └── 📁 sfs
│           │                       ├── 📄 ApiCallback.java
│           │                       ├── 📄 ApiClient.java
│           │                       ├── ...
│           │                       ├── 📁 api
│           │                       │   ├── 📄 DefaultApi.java
│           │                       │   └── 📄 SfsApi.java
│           │                       └── 📁 model
│           │                           ├── 📄 Share.java
│           │                           └── 📄 ResourcePool.java
│           └── 📁 test
└── 📄 settings.gradle

New Java SDK structure

📁 stackit-sdk-java
├── 📄 LICENSE.md
├── 📄 README.md
├── 📄 CHANGELOG.md
├── 📄 build.gradle
├── 📄 buildSrc
├── 📁 core
│   ├── 📄 CHANGELOG.md
│   ├── 📄 VERSION
│   ├── 📄 build.gradle
│   └── 📁 src
│       ├── 📁 main
│       │   └── 📁 java
│       │       └── 📁 cloud
│       │           └── 📁 stackit
│       │               └── 📁 sdk
│       │                   └── 📁 core
│       │                       ├── 📄 KeyFlowAuthenticator.java
│       │                       ├── 📄 KeyFlowInterceptor.java
│       │                       ├── 📁 auth
│       │                       └── ...
│       └── 📁 test
├── 📁 gradle
├── 📄 gradlew
├── 📄 gradlew.bat
├── 📁 services
│   ├── 📁 iaas
│   │   ├── 📄 CHANGELOG.md
│   │   ├── 📄 README.md
│   │   ├── 📄 VERSION
│   │   ├── 📄 build.gradle
│   │   └── 📁 src
│   │       ├── 📁 main
│   │       │   └── 📁 java
│   │       │       └── 📁 cloud
│   │       │           └── 📁 stackit
│   │       │               └── 📁 sdk
│   │       │                   └── 📁 iaas
│   │       │                       ├── 📁 v1api
│   │       │                       │    ├── 📄 ApiCallback.java
│   │       │                       │    ├── 📄 ApiClient.java
│   │       │                       │    ├── ...
│   │       │                       │    ├── 📁 api
│   │       │                       │    │   ├── 📄 DefaultApi.java
│   │       │                       │    │   └── 📄 IaasApi.java
│   │       │                       │    └── 📁 model
│   │       │                       │        ├── 📄 Server.java
│   │       │                       │        └── 📄 Volume.java
│   │       │                       ├── 📁 v2alpha1api
│   │       │                       │    ├── 📄 ApiCallback.java
│   │       │                       │    ├── 📄 ApiClient.java
│   │       │                       │    ├── ...
│   │       │                       │    ├── 📁 api
│   │       │                       │    │   ├── 📄 DefaultApi.java
│   │       │                       │    │   └── 📄 IaasApi.java
│   │       │                       │    └── 📁 model
│   │       │                       │        ├── 📄 Server.java
│   │       │                       │        └── 📄 Volume.java
│   │       │                       ├── 📁 v2beta1api
│   │       │                       │    ├── 📄 ApiCallback.java
│   │       │                       │    ├── 📄 ApiClient.java
│   │       │                       │    ├── ...
│   │       │                       │    ├── 📁 api
│   │       │                       │    │   ├── 📄 DefaultApi.java
│   │       │                       │    │   └── 📄 IaasApi.java
│   │       │                       │    └── 📁 model
│   │       │                       │        ├── 📄 Server.java
│   │       │                       │        └── 📄 Volume.java
│   │       │                       └── 📁 v2api
│   │       │                           ├── 📄 ApiCallback.java
│   │       │                           ├── 📄 ApiClient.java
│   │       │                           ├── ...
│   │       │                           ├── 📁 api
│   │       │                           │   ├── 📄 DefaultApi.java
│   │       │                           │   └── 📄 IaasApi.java
│   │       │                           └── 📁 model
│   │       │                               ├── 📄 Server.java
│   │       │                               └── 📄 Volume.java
│   │       └── 📁 test
│   └── 📁 sfs
│       ├── 📄 CHANGELOG.md
│       ├── 📄 README.md
│       ├── 📄 VERSION
│       ├── 📄 build.gradle
│       └── 📁 src
│           ├── 📁 main
│           │   └── 📁 java
│           │       └── 📁 cloud
│           │           └── 📁 stackit
│           │               └── 📁 sdk
│           │                   └── 📁 sfs
│           │                       └── 📁 v1api
│           │                           ├── 📄 ApiCallback.java
│           │                           ├── 📄 ApiClient.java
│           │                           ├── ...
│           │                           ├── 📁 api
│           │                           │   ├── 📄 DefaultApi.java
│           │                           │   └── 📄 SfsApi.java
│           │                           └── 📁 model
│           │                               ├── 📄 Share.java
│           │                               └── 📄 ResourcePool.java
│           └── 📁 test
└── 📄 settings.gradle

Migration guide

The migration guide is based on our resource manager code example. As you can see you basically have to only adjust your import statements.

- import cloud.stackit.sdk.resourcemanager.*;
+ import cloud.stackit.sdk.resourcemanager.v0api.*;

package cloud.stackit.sdk.resourcemanager.examples;

import cloud.stackit.sdk.core.exception.ApiException;
- import cloud.stackit.sdk.resourcemanager.api.ResourceManagerApi;
- import cloud.stackit.sdk.resourcemanager.model.CreateFolderPayload;
- import cloud.stackit.sdk.resourcemanager.model.CreateProjectPayload;
- import cloud.stackit.sdk.resourcemanager.model.FolderResponse;
- import cloud.stackit.sdk.resourcemanager.model.ListFoldersResponse;
- import cloud.stackit.sdk.resourcemanager.model.ListProjectsResponse;
- import cloud.stackit.sdk.resourcemanager.model.Member;
- import cloud.stackit.sdk.resourcemanager.model.OrganizationResponse;
- import cloud.stackit.sdk.resourcemanager.model.PartialUpdateFolderPayload;
- import cloud.stackit.sdk.resourcemanager.model.PartialUpdateProjectPayload;
- import cloud.stackit.sdk.resourcemanager.model.Project;
- import cloud.stackit.sdk.resourcemanager.wait.ResourcemanagerWait;
+ import cloud.stackit.sdk.resourcemanager.v0api.api.ResourceManagerApi;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.CreateFolderPayload;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.CreateProjectPayload;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.FolderResponse;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.ListFoldersResponse;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.ListProjectsResponse;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.Member;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.OrganizationResponse;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.PartialUpdateFolderPayload;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.PartialUpdateProjectPayload;
+ import cloud.stackit.sdk.resourcemanager.v0api.model.Project;
+ import cloud.stackit.sdk.resourcemanager.v0api.wait.ResourcemanagerWait;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;

final class ResourcemanagerExample {

	/** Prevent instantiation */
	private ResourcemanagerExample() {}

	@SuppressWarnings({"PMD.SystemPrintln"})
	public static void main(String[] args)
			throws IOException, ApiException, InterruptedException, ExecutionException {
		// Credentials are read from the credentialsFile in `~/.stackit/credentials.json` or the env
		// STACKIT_SERVICE_ACCOUNT_KEY_PATH / STACKIT_SERVICE_ACCOUNT_KEY
		ResourceManagerApi resourceManagerApi = new ResourceManagerApi();

		// Read the organization id and the member subject from the environment
		String organizationIdString = System.getenv("STACKIT_ORGANIZATION_ID");
		String memberSubjectString = System.getenv("STACKIT_MEMBER_SUBJECT");
		if (organizationIdString == null || organizationIdString.isEmpty()) {
			System.err.println("Environment variable 'STACKIT_ORGANIZATION_ID' not found.");
			return;
		}
		if (memberSubjectString == null || memberSubjectString.isEmpty()) {
			System.err.println("Environment variable 'STACKIT_MEMBER_SUBJECT' not found.");
			return;
		}
		UUID containerParentId = UUID.fromString(organizationIdString);

		Member member =
				new Member()
						.role("project.owner")
						.subject(memberSubjectString); // replace with an existing subject

		String labelName = "foo";
		/* create a project */
		Project project =
				resourceManagerApi.createProject(
						new CreateProjectPayload()
								.containerParentId(containerParentId.toString())
								.name("java-test-project")
								.addMembersItem(member)
								.labels(Collections.singletonMap(labelName, "bar")));
		System.out.println("Project:\n" + project.toString());

		/* list projects */
		ListProjectsResponse responseListProject =
				resourceManagerApi.listProjects(organizationIdString, null, null, null, null, null);
		System.out.println("Project List:\n" + responseListProject.toString());

		/* create a folder */
		FolderResponse folder =
				resourceManagerApi.createFolder(
						new CreateFolderPayload()
								.containerParentId(containerParentId.toString())
								.name("java-test-folder")
								.addMembersItem(member)
								.labels(Collections.singletonMap(labelName, "bar")));
		System.out.println("Folder: \n" + folder.toString());

		ResourcemanagerWait.createProjectWaitHandler(resourceManagerApi, project.getContainerId())
				.waitWithContextAsync()
				.get();

		/* list folders */
		ListFoldersResponse responseListFolders =
				resourceManagerApi.listFolders(organizationIdString, null, null, null, null, null);
		System.out.println("Folder List:\n" + responseListFolders.toString());

		/* delete a project label */
		resourceManagerApi.deleteProjectLabels(project.getContainerId(), Arrays.asList(labelName));

		/* delete a folder label */
		resourceManagerApi.deleteFolderLabels(folder.getContainerId(), Arrays.asList(labelName));

		/* update folder labels */
		resourceManagerApi.partialUpdateFolder(
				folder.getContainerId(),
				new PartialUpdateFolderPayload().labels(Collections.singletonMap("foo2", "bar2")));

		/* update project move to created folder */
		resourceManagerApi.partialUpdateProject(
				project.getContainerId(),
				new PartialUpdateProjectPayload().containerParentId(folder.getContainerId()));

		ResourcemanagerWait.updateProjectWaitHandler(resourceManagerApi, project.getContainerId())
				.waitWithContextAsync()
				.get();

		/* get organization details */
		OrganizationResponse organizationResponse =
				resourceManagerApi.getOrganization(organizationIdString);
		System.out.println("Organization List:\n" + organizationResponse.toString());

		/* since you cannot delete a folder when a project is present we need to move the project out again */
		resourceManagerApi.partialUpdateProject(
				project.getContainerId(),
				new PartialUpdateProjectPayload().containerParentId(organizationIdString));

		/* delete project */
		resourceManagerApi.deleteProject(project.getContainerId());

		/* wait for the project deletion to complete */
		ResourcemanagerWait.deleteProjectWaitHandler(resourceManagerApi, project.getContainerId())
				.waitWithContextAsync()
				.get();

		/* delete folder */
		resourceManagerApi.deleteFolder(folder.getContainerId(), null);
	}
}