Upcoming multi API version support in the STACKIT Go SDK

[rubenhoenle]

As of now every of the SDK modules in the STACKIT Go 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 Go 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

The old SDK structure is entirely marked as deprecated and will be removed after 2026-09-30, so you have enough time to switch to the new API-version specific packages.

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

Old Go SDK structure

📁 stackit-sdk-go
├── 📄 LICENSE
├── 📄 README.md
├── 📄 CHANGELOG.md
├── 📁 core
│   ├── 📄 CHANGELOG.md
│   ├── 📄 VERSION
│   ├── 📁 auth
│   ├── 📄 go.mod
│   ├── 📄 go.sum
│   └── ...
└── 📁 services
    ├── 📁 iaas
    │   ├── 📄 CHANGELOG.md
    │   ├── 📄 VERSION
    │   ├── 📄 api_default.go
    │   ├── 📄 client.go
    │   ├── 📄 go.mod
    │   ├── 📄 go.sum
    │   ├── 📄 model_server.go
    │   ├── 📄 model_volume.go
    │   └── 📁 wait
    │       ├── 📄 wait.go
    │       └── 📄 wait_test.go
    └── 📁 secretsmanager
        ├── 📄 CHANGELOG.md
        ├── 📄 VERSION
        ├── 📄 api_default.go
        ├── 📄 client.go
        ├── 📄 go.mod
        ├── 📄 go.sum
        ├── 📄 model_instance.go
        ├── 📄 model_user.go
        └── 📁 wait
            ├── 📄 wait.go
            └── 📄 wait_test.go

New Go SDK structure

📁 stackit-sdk-go
├── 📄 LICENSE
├── 📄 README.md
├── 📄 CHANGELOG.md
├── 📁 core
│   ├── 📄 CHANGELOG.md
│   ├── 📄 VERSION
│   ├── 📁 auth
│   ├── 📄 go.mod
│   ├── 📄 go.sum
│   └── ...
└── 📁 services
    ├── 📁 iaas
    │   ├── 📄 CHANGELOG.md
    │   ├── 📄 VERSION
    │   ├── 📄 go.mod
    │   ├── 📄 go.sum
    │   ├── 📄 api_default.go    # deprecated
    │   ├── 📄 client.go         # deprecated
    │   ├── 📄 model_server.go   # deprecated
    │   ├── 📄 model_volume.go   # deprecated
    │   ├── 📁 wait              # deprecated
    │   │   ├── 📄 wait.go       # deprecated
    │   │   └── 📄 wait_test.go  # deprecated
    │   ├── 📁 v1
    │   │   ├── 📄 api_default.go
    │   │   ├── 📄 client.go
    │   │   ├── 📄 model_server.go
    │   │   └── 📄 model_volume.go
    │   ├── 📁 v2
    │   │   ├── 📁 wait
    │   │   │   ├── 📄 wait.go
    │   │   │   └── 📄 wait_test.go
    │   │   ├── 📄 api_default.go
    │   │   ├── 📄 client.go
    │   │   ├── 📄 model_server.go
    │   │   └── 📄 model_volume.go
    │   ├── 📁 v2alpha1
    │   │   ├── 📄 api_default.go
    │   │   ├── 📄 client.go
    │   │   ├── 📄 model_server.go
    │   │   └── 📄 model_volume.go
    │   └── 📁 v2beta1
    │       ├── 📄 api_default.go
    │       ├── 📄 client.go
    │       ├── 📄 model_server.go
    │       └── 📄 model_volume.go
    └── 📁 secretsmanager
        ├── 📄 CHANGELOG.md
        ├── 📄 VERSION
        ├── 📄 go.mod
        ├── 📄 go.sum
        ├── 📄 api_default.go      # deprecated
        ├── 📄 client.go           # deprecated
        ├── 📄 model_instance.go   # deprecated
        ├── 📄 model_user.go       # deprecated
        ├── 📁 wait                # deprecated
        │   ├── 📄 wait.go         # deprecated
        │   └── 📄 wait_test.go    # deprecated
        └── 📁 v1
            ├── 📄 api_default.go
            ├── 📄 client.go
            ├── 📄 model_instance.go
            ├── 📄 model_user.go
            └── 📁 wait
                ├── 📄 wait.go
                └── 📄 wait_test.go

Migration guide

See the code example below how to migrate to the new SDK structure. This migration guide is based on the resourcemanager SDK example.

Note that at the same time we provide you with the multi API version support in the Go SDK we also improved our SDK generator to produce a more reliable SDK output. That's why some datatypes have changed in the new SDK packages.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/stackitcloud/stackit-sdk-go/core/utils"
-	"github.com/stackitcloud/stackit-sdk-go/services/resourcemanager"
+	resourcemanager "github.com/stackitcloud/stackit-sdk-go/services/resourcemanager/v0api"
)

func main() {
	// Specify the parent organization ID
	parentOrganizationId := "ORGANIZATION_ID"

	// Create a new API client, that uses default authentication and configuration
	client, err := resourcemanager.NewAPIClient()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Creating API client: %v\n", err)
		os.Exit(1)
	}

	// Get the projects under a specific resource (organization)
-	getProjectsResp, err := client.ListProjects(context.Background()).ContainerParentId(parentOrganizationId).Execute()
+	getProjectsResp, _, err := client.DefaultAPI.ListProjects(context.Background()).ContainerParentId(parentOrganizationId).Execute()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `GetProjects`: %v\n", err)
	} else {
-		fmt.Printf("Number of projects: %v\n", len(*getProjectsResp.Items))
+		fmt.Printf("Number of projects: %v\n", len(getProjectsResp.Items))
	}

	// Create a project
	createProjectPayload := resourcemanager.CreateProjectPayload{
-		ContainerParentId: utils.Ptr(parentOrganizationId),
+		ContainerParentId: parentOrganizationId,
-		Name:              utils.Ptr("my-project"),
+		Name:              "my-project",
-		Members: &[]resourcemanager.Member{
+		Members: []resourcemanager.Member{
			{
-				Role:    utils.Ptr("project.owner"),
+				Role:    "project.owner",
-				Subject: utils.Ptr("owner-email@example.com"),
+				Subject: "owner-email@example.com",
			},
		},
	}
-	createProjectResp, err := client.CreateProject(context.Background()).CreateProjectPayload(createProjectPayload).Execute()
+	createProjectResp, _, err := client.DefaultAPI.CreateProject(context.Background()).CreateProjectPayload(createProjectPayload).Execute()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `CreateProject`: %v\n", err)
	} else {
-		fmt.Printf("Created project with id \"%s\".\n", *createProjectResp.ProjectId)
+		fmt.Printf("Created project with id \"%s\".\n", createProjectResp.ProjectId)
	}
}

[h3adex]

Sound good! Happy to hear that :-)