Logo der codecentric AG, einem in Deutschland führenden IT-Consulting Unternehmen

Logo der codecentric AG einem in Deutschland führenden IT-Consulting Unternehmen

Cloud-Native

Data & Machine Learning

Generative KI

IT-Security

Produktentwicklung

Weitere Leistungen...

Leistungen

Arbeitsweise

Projekte

Berlin

Bielefeld

Dortmund

Erfurt

Frankfurt am Main

Hamburg

Karlsruhe

Leipzig

München

Münster

Nürnberg

Solingen

Stuttgart

Standorte

Blog

Softwerker

Fachmedien

Webinare

Events

Wissens-Hub

Unsere Kultur

Kultur & Karriere Podcast

Deine Entwicklung

Jobs

Karriere

Über uns

Aktuelles

Kontakt

Alle Standorte

Du hast Fragen oder möchtest dich mit mir austauschen? Gern – trag einfach deine Kontaktdaten ein.

Contact Us | Sub-Navi-Kontakt oder Zero Search Hits

Kontakt aufnehmen

Marketing & Community Management

Konntest du keine Einträge zu deinem Thema finden?  

STANDORT-TEAM

codecentric Stuttgart

Unser codecentric Team am Standort Stuttgart stellt sich vor.

codecentric Team Stuttgart

Willkommen im Team Stuttgart

<p>Golang, a.k.a. Go, has been around in the industry for quite some time now, but people are still reluctant to just go ahead and use it. To help you get started, follow me on this journey and create your first microservice using Golang, Gin and Docker.</p><h2>Set up your environment</h2><p>There are a few packages needed on your development system in order to start developing – the good news is that it’s not much and easy to install:</p><ol><li><a href="https://golang.org/doc/install" target="_blank">Install Golang</a> </li><li><a href="https://docs.docker.com/get-docker/" target="_blank">Install Docker</a> </li></ol><p>In the upcoming sections I’m assuming that you are using Golang 1.11 or newer. If you, however, use an older version, be aware that some things might not work as described here.</p><p>If you want to get the whole application right from the start, you can go ahead and clone the Git repository right <a href="https://github.com/Andreas-Maier/task-management" target="_blank">here</a>  from GitHub.</p><h2>Let the coding begin</h2><h3>Basics</h3><p>Assuming you successfully installed and tested Golang, let’s see how to get going and set up a webservice using <a href="https://github.com/gin-gonic/gin" target="_blank">Gin</a> .<br /> First of all, we need our main package with the main function in our <em>main.go</em> file (that’s enough mains for now) 🙂</p>

```

package main

import "log"

func main() {
	log.Println("Hello from Go")
}

```

<p>By running <code>go build</code> in your terminal, an executable suitable for your operating system will be created. By running said executable, we should already see the output “Hello from Go”.</p><p>Before adding external dependencies, it is worth considering adding support for versioned modules to our application by running <code>go mod init task-management</code>. Feel free to change the name of the application from <em>task-management</em> to anything you want!<br /> We will see that a new file <code>go.mod</code> appears in your directory. Afterwards, we will find all dependencies we’re adding to our application in there.</p><p>Now let’s put some Gin in there and get our webservice started!</p><p>We can include Gin just like any other dependency in Go (assuming you run version 1.11 or newer) by running <code>go get -u github.com/gin-gonic/gin</code>.<br /> This will download the Gin dependency and add it to the <code>go.mod</code> file. Now we recognize yet another new file in our directory – <code>go.sum</code>. That file contains checksums for direct and indirect dependencies of our application and actually some more things not that relevant for our cause.</p><h3>Setting up Gin and your first endpoint</h3><p>Now that we have Gin included, let’s set up and start the server.</p>

```

package main

import "github.com/gin-gonic/gin"

func main() {
	r := gin.Default()
	r.Run()
}

```

<p>Yes, that’s all we need to set up Gin. Using <code>go build</code> to build the application and then running the created executable will show us where we can reach Gin (should be <code>curl localhost:8080</code> on default). That will give us an HTTP status 404 and some log output indicating that we’re set up and are successfully serving HTTP errors!</p><h3>Serving some data</h3><p>Now, while serving HTTP error codes can be fun, accompany me on our journey and start serving some actual data. Let’s go ahead and think about what data we want to serve. As mentioned above, I would just serve tasks as a start.</p><p>To separate the model from the application logic, we can put the struct into a separate file <code>task.go</code></p>

```

package main

// Task - Model of a basic task
type Task struct {
	Title string
	Body  string
}

```

<p>Now let’s serve a task (as JSON) through a few modifications in our <code>main.go</code> file:</p>

```

package main

import "github.com/gin-gonic/gin"

func handleGetTasks(c *gin.Context) {
	var tasks []Task
	var task Task
	task.Title = "Bake some cake"
	task.Body = `- Make a dough 
	- Eat everything before baking 
	- Pretend you never wanted to bake something in the first place`

	tasks = append(tasks, task)
	c.JSON(http.StatusOK, gin.H{"tasks": tasks})
}

func main() {
	r := gin.Default()
	r.GET("/tasks/", handleGetTasks)
	r.Run()
}

```

<p>If we go ahead and <code>go build</code> and then run the application, we will now be able to see the dummy task as JSON by hitting <code>localhost:8080/tasks/</code></p><p>We can now see that a pointer to the <code>gin.Context</code> object is passed to each handler function we add to Gin (e.g. <code>handleGetTasks</code>). That context can then be used to interact with parameters or objects passed in the request but also to specify what you want to return in terms of status code, headers and content. Furthermore, be aware that the <code>gin</code> type is always available to you if you import it and it offers quite a few handy functions to interact with request and response types. Therefore make sure to check if Gin offers functions you need before writing everything yourself!</p><h3>Setting up a MongoDB for your application</h3><p>There are multiple ways we could choose to just store some data, but to make things a bit more interesting, we could store our data in a <a href="https://www.mongodb.com/" target="_blank">MongoDB</a> .</p><p>As we already have Docker installed on our development environment, we can use that to run our own MongoDB instance locally.</p><p>Executing <code>docker run --name mongodb -e MONGO_INITDB_ROOT_USERNAME=myuser -e MONGO_INITDB_ROOT_PASSWORD=mypassword -e MONGO_INITDB_DATABASE=tasks -p 27017:27017 -d mongo:latest</code> should be fine for development purposes (of course not for productive use!)</p><h3>Storing data in our MongoDB</h3><h4>Connecting to MongoDB</h4><p>As we now have our MongoDB, we need to establish a connection from our Golang application. Luckily, there also is a dependency we can use to make things easier for us: <code>go get -u go.mongodb.org/mongo-driver</code>.</p>

```


...package declaration and imports...

const (
	// Timeout operations after N seconds
	connectTimeout           = 5
	connectionStringTemplate = "mongodb://%s:%s@%s"
)

// GetConnection - Retrieves a client to the DocumentDB
func getConnection() (*mongo.Client, context.Context, context.CancelFunc) {
	username := os.Getenv("MONGODB_USERNAME")
	password := os.Getenv("MONGODB_PASSWORD")
	clusterEndpoint := os.Getenv("MONGODB_ENDPOINT")

	connectionURI := fmt.Sprintf(connectionStringTemplate, username, password, clusterEndpoint)

	client, err := mongo.NewClient(options.Client().ApplyURI(connectionURI))
	if err != nil {
		log.Printf("Failed to create client: %v", err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), connectTimeout*time.Second)

	err = client.Connect(ctx)
	if err != nil {
		log.Printf("Failed to connect to cluster: %v", err)
	}

	// Force a connection to verify our connection string
	err = client.Ping(ctx, nil)
	if err != nil {
		log.Printf("Failed to ping cluster: %v", err)
	}

	fmt.Println("Connected to MongoDB!")
	return client, ctx, cancel
}

```

<p>While this looks like a lot of code, please note that now we have everything we need to start interacting with our MongoDB including timeouts, configurability and connectivity checks. Nevertheless, it might make sense to put that into a separate file e.g. <code>db.go</code>. Also, we should create a file containing our environment variables (e.g. a <code>.env</code> file) with entries like: <code>export MONGODB_USERNAME=myuser</code>.</p><p>In the <code>getConnection()</code> function, be aware that we are using <code>os</code> to interact with our environment. In contrast to many other languages, Golang makes it really easy to get in contact with the environment and read or write environment variables in pretty much just one line of code.</p><h4>Adding a Datamodel</h4><p>Now let’s tackle the next obstacle and start storing some data in our MongoDB. Therefore we need some changes.<br /> To make each entry easily identifiable, we should add an ID field to our task struct:</p>

```

...
type Task struct {
	ID    primitive.ObjectID 
	Title string
...

```

<h4>Interacting with our MongoDB</h4><p>In our <code>db.go</code> we should now add some code to actually create a new task in our MongoDB collection.</p>

```

//Create creating a task in a mongo or document db
func Create(task *Task) (primitive.ObjectID, error) {
	client, ctx, cancel := getConnection()
	defer cancel()
	defer client.Disconnect(ctx)
	task.ID = primitive.NewObjectID()

	result, err := client.Database("tasks").Collection("tasks").InsertOne(ctx, task)
	if err != nil {
		log.Printf("Could not create Task: %v", err)
		return primitive.NilObjectID, err
	}
	oid := result.InsertedID.(primitive.ObjectID)
	return oid, nil
}

```

<p>As you can see, we pass a pointer to the task object into the <em>create</em> function, generate a new ObjectID and then use our MongoDB client to store the task in our collection. As a result, we pass the ObjectID, or an error in case something unintended happens while saving.</p><p>In Golang we can defer the execution of code to when the function is exited. This is a really nice way to free resources and acquired connections like our MongoDB connection. We can make sure to close the connection in any case and schedule it to close automatically once the functions exits.</p><p>Finally, we should hook a handler in our <code>main.go</code> and call the <code>Create</code> function we’ve just written:</p>

```

...
func handleCreateTask(c *gin.Context) {
	var task Task
	if err := c.ShouldBindJSON(&task); err != nil {
		log.Print(err)
		c.JSON(http.StatusBadRequest, gin.H{"msg": err})
		return
	}
	id, err := Create(&task)
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"msg": err})
		return
	}
	c.JSON(http.StatusOK, gin.H{"id": id})
}

func main() {
	r := gin.Default()
	r.GET("/tasks/", handleGetTasks)
	r.PUT("/tasks/", handleCreateTask)
	r.Run()
}

```

<p>As you can see here, Gin helps us marshal and bind the JSON string into our task to make our lives a bit easier. It also assists us in handling conversion errors on our own with <code>ShouldBind...</code> or Gin handles everything for us with <code>Bind...</code> if we decide to.</p><h4>Let’s build everything and try it!</h4><p>Now <code>go build</code>, specify the environment variables (MONGODB_USERNAME, MONGODB_PASSWORD and MONGODB_ENDPOINT), run the application, and store a new task in our MongoDB:<br /> <code> curl --location --request PUT 'http://localhost:8080/tasks/' \ --header 'Content-Type: application/json' \ --data-raw '{ "Title": "New Task", "Body": "Well this has been some fun already!" }' </code></p><p>Now we can change the <code>GET</code> endpoint to return the data that is actually stored in MongoDB, add <code>DELETE</code> and <code>POST</code> endpoints and so on and so forth.<br /> You can find implementations of those endpoint in the <a href="https://github.com/Andreas-Maier/task-management" target="_blank">GitHub project</a> , but I think now it’s time to move on to our next and last chapter.</p><h3>Containerize it!</h3><p>What would a proper microservice be without a comfy and tiny Docker container? As Golang has huge support for container technologies, this is quite easy. You can actually start from scratch! 😀</p>

```

FROM scratch
ENV MONGODB_USERNAME=MONGODB_USERNAME MONGODB_PASSWORD=MONGODB_PASSWORD MONGODB_ENDPOINT=MONGODB_ENDPOINT
# My application runnable is called gin here
ADD gin / 
CMD ["/gin"]

```

<p>Now if you have built your container and try to run it, you might see a strange error <code>standard_init_linux.go:211: exec user process caused "exec format error"</code>. This happens if you’ve built the Golang application on a different operating system than you try to run it on. In case of Windows, Docker might even have trouble locating a file named <em>gin</em> at all.</p><p>We have multiple ways of dealing with this issue:</p><ol><li>Build the Go application for the OS we run the application on</li><li>Do a multistage Docker build</li></ol><p>If you want to follow route one on our journey, you simply need to execute <code>GOOS=linux go build</code> when building the application and next time you build our container, everything should be fine. This is a really handy feature as you can compile Golang applications for different operating systems by just specifying the GOOS environment variable.</p><p>If you want a multistage Docker build, you need a few more lines of code but your overall build process will be much simpler and more automated:</p>

```

FROM golang:latest AS builder
ADD . /app
WORKDIR /app
RUN go mod download
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o /main .

FROM scratch
ENV MONGODB_USERNAME=MONGODB_USERNAME MONGODB_PASSWORD=MONGODB_PASSWORD MONGODB_ENDPOINT=MONGODB_ENDPOINT
COPY --from=builder /main ./
ENTRYPOINT ["./main"]
EXPOSE 8080

```

<p>Now you can build and run your container and are good to go!</p><h2>Famous last words</h2><p>Now, having built this application, you might have realized that Golang is actually quite nice. Yes, some things are rather expressive and might seem a bit repetitive (error handling, I’m looking at you), but you can build applications really fast and they actually are quite readable if you are used to C/C++/C# or other related languages. Overall, it’s a fun language to use. Make sure to go ahead and gather your own experiences with it! 🙂</p><p>If you want to check out the whole project, fill any gaps or just start experimenting based on this application – <a href="https://github.com/Andreas-Maier/task-management" target="_blank">Clone me on GitHub!</a> . Pull requests are very welcome! 🙂</p><p>Share your thoughts with me using the comment section below and check out the blog – there might be more you’re interested in, e.g. <a href="/wissens-hub/blog/serverless_gcp-look_ma_no_servers/">Serverless Golang on GCP</a> !</p>

Golang, Gin & MongoDB – Building microservices easily

Imagine the following situation: You are building a serverless application using e.g. lambdas, you setup your system using CDK (or CloudFormation) and you store your data in Aurora Serverless. How would you automate your database schema adaptations or prefilling tables in your database? You don't know when your lambdas are going to get started. You don't know how many there may be. Maybe you have multiple services that connect to the same datastore and don't have a good fit where to include your upgrades?

Why not manage your database schema changes within your infrastructure setup with CDK? In this blog article I will describe how you can set up a CDK stack that handles database changes with Liquibase when you deploy your infrastructure changes using an example for you to try alongside in your own AWS account.  


## Setup/Preconditions

As mentioned above, the approach will use CDK. Therefore I recommend [installing CDK on your machine alongside its prerequisites](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites), if you want to follow along and deploy the example in your own AWS account. Also Docker will be used when deploying the stacks into your AWS account and therefore needs to be [installed on your machine](https://docs.docker.com/get-docker/), if you want to follow along.

If you have not used CDK before, you should also make sure that the AWS account you want to use is [bootstrapped](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_bootstrap) and if it is not, run `cdk bootstrap aws://ACCOUNT-NUMBER/REGION`.

## How do we do all this?
### Architecture/Component Overview

The example is composed out of multiple stacks to separate the different components that are used. 
1. We have an application stack that sets up our networking components, like a VPC, security groups and creates our database and database migration stack.
2. Next we have a stack to create and configure everything for our Aurora Serverless database.
3. Last but not least we have a stack that includes everything we need to do automatic database upgrades with Liquibase. 

The picture below depicts the used constructs and stacks to give more of an overview over the solution.

![Overview_Serverless_RDS_Upgrades.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/3rL5YO55QOyqsexgHFY4)

As I will reference files directly in the following description I recommend checking out the source code of the example application, or at least to have a look on [GitHub](https://github.com/Andreas-Maier/serverless-rds-updates)! 

### Networking infrastructure

The networking setup for this setup is nothing special and can be found in the `application-stack.ts`. However, it is needed as the Aurora Serverless will be deployed in a VPC and in most cases in the private subnets of said VPC. Therefore we need some configuration to enable our Lambda to talk to Aurora Serverless. 

We use two separate security groups to configure access to the database and the Lambda and by adding an ingress rule we can allow our database migration security group to pass through our database security group on the default postgresql port `5432`.  

```
const databaseSecurityGroup = new SecurityGroup(
    this,
    "DatabaseSecurityGroup",
    {
        securityGroupName: "DatabaseSecurityGroup",
        vpc,
    }
);
const databaseMigrationSecurityGroup = new SecurityGroup(
    this,
    "DatabaseMigrationSecurityGroup",
    {
        securityGroupName: "DatabaseMigrationSecurityGroup",
        vpc,
    }
);
databaseSecurityGroup.addIngressRule(
    databaseMigrationSecurityGroup,
    Port.tcp(5432),
    "allow access for database migration lambda"
);
```


### RDS Aurora Serverless

As for the networking components, the RDS Aurora Serverless setup is rather standard and can be found in the `database-stack.ts`. The database credentials are created when the database stack is created and the credential is safely stored in AWS SecretsManager for our database migration Lambda to access it later. 

```
this.credentials = Credentials.fromGeneratedSecret(username, {
    secretName: "/aurora/databaseSecrets",
});
```

We also limit the subnets our database cluster can use to only our private subnets.
```
const databaseSubnetGroup = new SubnetGroup(this, "DatabaseSubnetGroup", {
    description: "SubnetGroup for Aurora Serverless",
    vpc: props.vpc,
    vpcSubnets: props.vpc.selectSubnets({
        subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    }),
});
```



As of right now, only a few Postgresql versions are supported with Aurora Serverless, hence the Postgres engine version 11.16. I recommend checking for newer supported versions when you set up an Aurora Serverless cluster using Postgres.

```
this.database = new ServerlessCluster(this, "DemoCluster", {
    engine: DatabaseClusterEngine.auroraPostgres({
        version: AuroraPostgresEngineVersion.VER_11_16,
    }),
    credentials: this.credentials,
    defaultDatabaseName: "demo",
    vpc: props.vpc,
    subnetGroup: databaseSubnetGroup,
    securityGroups: [props.databaseSecurityGroup],
    scaling: {
        autoPause: Duration.minutes(5),
        minCapacity: AuroraCapacityUnit.ACU_2,
        maxCapacity: AuroraCapacityUnit.ACU_4,
    },
});
```

The scaling options are set to a minimum for this demo case and also include shutting down the database if there is no activity for 5 minutes. This can result in longer startup times.

## Database migration with CDK Custom Resource

Now that the surrounding infrastructure is defined, we can take care of the infrastructure components we need for the database migration. 

In total we will need two policy statements for the Lambda, one role that is used while executing the Lambda, the Lambda function itself, a custom resource provider and a custom resource. 

As mentioned while setting up the Aurora Serverless, we store the credentials to access our database in AWS SecretsManager. Therefore we need to allow our Lambda to access the SecretsManager by creating the `secretsManagerPolicyStatement`. Also, as hinted while creating the network infrastructure, we need to allow our Lambda to run in a VPC. In AWS this is achieved through an elastic network interface (ENI) that the Lambda creates and connects to. The lambda can then access services that are located in private subnets of the VPC through the ENI that is being deployed in the VPC. This is allowed through the policy statement `createENIPolicyStatement`.

![VPC-ENI.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/Qw5IT127SdaaXodJV2Hg)

For the policies to take effect while executing the lambda, we create a role that extends the `AWSLambdaBasicExecutionRole` managed policy by adding the previously described policies. 

Let's take a look at the lambda function. As the function is using Liquibase and is written in Java, we need to set the runtime to a currently supported Java runtime. In this case we opt for Java 11 which will be `Amazon Corretto`. 

In order for the Lambda to fetch the secret from SecretsManager, we need to pass the region and secret name into the function. In this case we can use environment variables, as the secret name itself does not need special protection.
 
To further tell the lambda to connect to our VPC during execution time, we need to set the VPC, SecurityGroup and subnets to use by the Lambda. As our function has no need to be available to the general public, we can limit it to only use private subnets. Also, to allow the lambda to create and attach to ENIs we need to set our previously created role for the Lambda.   

#### Building and bundling the Maven function for Lambda 

Lambdas in CDK come with a nice feature. You can define a build process for your Lambda when you define the Lambda itself. When you specify where your code assets are located you have a set of options to apply also. One of those is a bundling option. This may be used to build your code and package it. 
For our use case this is quite handy, as we need to run a maven build and by specifying it in CDK directly, we do not need to add any other build and package systems. 

AWS provides a set of predefined images you can use to build your software. The Java 11 building image contains Java and Maven and thereby everything we need to build and package our software. The Lambda function will simply get the code by putting the built and bundled artifact in the `asset-output` directory. 


```
const databaseMigrationFunction = new Function(
    this,
    "DatabaseMigrationFunction",
    {
        runtime: Runtime.JAVA_11,
        code: Code.fromAsset(path.join(__dirname, "./database-migration"), {
            bundling: {
            image: Runtime.JAVA_11.bundlingImage,
            user: "root",
            outputType: BundlingOutput.ARCHIVED,
            command: [
                "/bin/sh",
                "-c",
                "mvn clean install " +
                "&& cp /asset-input/target/databaseMigration.jar /asset-output/",
            ],
            },
        }),
        handler: "migration.Handler",
        environment: {
            DATABASE_SECRET_NAME: props.credentials.secretName!,
            REGION: props.database.env.region,
        },
        vpc: props.vpc,
        vpcSubnets: props.vpc.selectSubnets({
            subnetType: SubnetType.PRIVATE_WITH_EGRESS,
        }),
        securityGroups: [props.databaseMigrationSecurityGroup],
        timeout: Duration.minutes(5),
        memorySize: 512,
        role: databaseMigrationFunctionRole,
    }
);
```

In order to run our database migration Lambda when deploying our infrastructure, we need to specify a CDK custom resource provider. By referencing our Lambda in the `onEventHandler`, our Lambda is called for every create, modify and delete event of the custom resource. 

```
const databaseMigrationFunctionProvider = new Provider(
    this,
    "DatabaseMigrationResourceProvider",
    {
        onEventHandler: databaseMigrationFunction,
    }
);
```


Now that we have a custom resource provider, we can go ahead and specify the custom resource associated. If we would only specify the custom resource and point it to the custom resource provider service token, our Lambda would be executed once upon creation of the resource. Now this is a problem, if you want to have continuous database upgrades without destroying resources regularly. Therefore, we need the custom resource to change with every deployment so liquibase can check for necessary database upgrades. 

An easy solution to achieve this is by adding a date property to the resource and setting the current date and time so we have an ever changing value. 

```
new CustomResource(this, "DatabaseMigrationResource", {
    serviceToken: databaseMigrationFunctionProvider.serviceToken,
    properties: {
        date: new Date(Date.now()).toUTCString(),
    },
});
```



### The database migration code

The database migration is done using [Liquibase](https://www.liquibase.org/). As Liquibase requires Java to run we also write our Lambda in Java. AWS offers good [documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) on how to write Lambda functions using Java so most of the general handler setup and dependencies can be found there. For our use case, we need to add secretsmanager, liquibase-core and postgresql to our Maven dependencies in the `pom.xml`. 

Now as you may notice in our `Handler.java` class we do not implement the basic `RequestHandler` as a regular lambda would do. By extending the `AbstractCustomResourceHandler` we give our lambda a few methods to implement depending on what happens to our CDK resource. For this example we want to run the database migration when the cdk resource is created as well as when an update is happening. For a CDK resource deletion Liquibase is not executed – this however can be different depending on your use case! 

For the `migrateDatabase`method to actually migrate something, we first need to fetch the secret from AWS SecretsManager in order to connect to the database. This way the secret is managed in a single safe place, access to the secret can be granted in a detailed manner and there is no secret information buried in environment variables. 

The rest of the `migrateDatabase` method is kept rather simple but still creates a database connection, starts up a Liquibase context and runs the upgrades described in the Liquibase changelog. 

The Liquibase changelog, located in `src/main/resources/liquibase`, just contains two changesets for the database schema creation and an example table so we can see that the migration happened and something has changed. 


## Deploy the Stacks

As we have taken a look at the components and some of the configuration we can deploy our CDK stacks. If you want to try this yourself, I encourage you to checkout the [GitHub repo](https://github.com/Andreas-Maier/serverless-rds-updates) with all the necessary code. I've left out some more general stuff in this blog post, but you can check out the whole thing on Github and run it from there. 

To deploy our three stacks to your locally configured AWS account, all you need to do is run `cdk deploy --all`. 

Also good to know if you want to clean up afterwards: All you need to run is `cdk destroy --all` and optionally delete any remaining log groups in CloudWatch. (Destroying the stacks may take a while)

## What happened in the AWS account/Where can I see results?

Let's assume you deployed the stack and get this nice message in your console: 

```
 ✅  ServerlessRdsUpdatesStack/DatabaseMigrationStack
```


Now you might wonder, what happened? How can I see if the database migration was executed?

Let's check the AWS console to see if everything worked as it should have. So first of all log into the AWS account you deployed the stack to and navigate to the CloudFormation Service. There you should be able to find our three stacks in `CREATE_COMPLETE` status. 

![Cloudformation_Status_Serverless_RDS_Upgrades.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/Tfko4pRBSKq5hGYZeXV2) 

With this checked we can go ahead and see if our database migration ran and created the table we wanted. Therefore we need to open AWS SecretsManager and RDS. 

In AWS SecretsManager we need to check the list of secrets for a secret named `/aurora/databaseSecrets`. When checking the details we need to take note of the ARN of this secret, because this is what we need to connect to our database in a minute. If you want to, you can also check username, password and other details that may be needed to connect to the database by clicking on the `retrieve the secret value` button.

In the RDS service we can open up the Query Editor and directly access a database using a secret from the SecretsManager. So let's open up the RDS Query Editor, choose the database we just created, choose to connect using a Secrets Manager ARN, and enter the ARN of the secret we just noted. Note if you used the demo, the database name will just be demo and afterwards you should be ready to connect to the database. 

After connecting, there is a Query Editor that we can use to query our database. We can see that there is a query prefilled and we can use that to see if our Liquibase migration was executed. Therefore we can just hit the run button to execute the query. After the query is executed we can find our new users table in the result windows. 

![RDS_Tables_Query_Result_Serverless_RDS_Upgrades.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/TYLpbnBPTO6KSRUl8cnc) 

To now interact with the table you can feel free to select. insert or delete operation on the table `demo.users` using the Query Editor.

## Conclusion

Automation of deployment and change processes is a very important topic for many projects. Moving faster and getting features out quicker and more reliable is pretty much inevitable. Due to this, automating every bit of your deployment is a necessity. Therefore, if you run into a situation where you are wondering how to automate upgrades of your relational database this solution might be something for you to consider. However, if you have no good reason to use a relational database, I encourage you to also have a look at schemaless options like DynamoDB. 

How to upgrade your Aurora Serverless database schema using CDK and Lambda

People Lead & IT Consultant

<p>Der erste Hackergarten Stuttgart fand am 23. Juli 2015 statt. Das Ziel dieses Hacks war ein verschlüsseltes Ping-Pong zweier embedded Funküberträgern.</p><p>Die Idee für den Hack stammt vom Heimautomatisierungsprojekt eines Hackers. Anscheinend gibt es Nachholbedarf im Bereich verschlüsselter Funkübertragungs-Protokolle – sowohl Software als auch Hardware. Wenn man etwas richtig haben will, muss man es eben selbst machen (DIY – Do it yourself).<br /> Das Ziel dieses Hacks ist der Aufbau einer Funkverbindung zwischen Gateway und KNotizn, mit einem anschließend verschlüsseltem Ping-Pong (Anfrage-Antwort).</p><h2>Verwendete Hardware</h2><p>Beim Hackathon war folgende Hardware im Einsatz:</p><ul><li>1x Seeeduino v3.0</li><li>1x <a href="http://www.sainsmart.com/sainsmart-uno-r3-atmega328-au-development-board-compatible-with-arduino-uno-r3.html" name="SainSmart UNO R3">SainSmart UNO R3</a> </li><li>2x RFM69HW: -120dBm 433/868/915Mhz RF Transceiver Module</li><li>Kleinigkeiten wie Kabel, Lötzinn…</li></ul>

```
Tipp:
Aufgepasst, der RFM69HW hat eine Betriebsspannung von 3.3V. Der angeschlossene Arduino benötigt also einen 3,3V Ausgang oder ihr verwendet ein Netzteil mit 3.3V Spannung.
```

<h2>Verwendete Software</h2><ul><li><a href="https://www.arduino.cc/en/Main/Software" name="Arduino Software">Arduino-Software</a> </li><li><a href="https://github.com/LowPowerLab/RFM69" name="RFM69 library for RFM69W and RFM69HW">RFM69 Bibliothek für RFM69W und RFM69HW</a> </li><li><a href="https://github.com/LowPowerLab/SPIFlash" name="Arduino library for read/write access to SPI flash memory chips">Arduino Bibliothek für Lese-/Schreibzugriff auf SPI-Flash-Memory-Chips</a> </li></ul>

```
Tipp:
Der Seeeduiono hat einen FTDI-USB-Chip. In dieser Anleitung wird gut erklärt, wie man den richtigen 
USB-Treiber installiert.
```

<h2>Aufbau</h2><p>Da man mit der Arduino-Software nur einen seriellen Monitor anzeigen lassen kann, empfielt es sich, ein separates Programm hierfür zu haben (z.B. <a href="http://freeware.the-meiers.org/">CoolTerm</a> ), einen weiteren Rechner, oder den seriellen Monitor von Arduino zu Arduino umzuschalten.</p>

```
Tipp:
Wir hatten zwei Macs. Das erleichterte das gleichzeitige Hacken.
```

<h3>Hardware-Aufbau</h3><div><a href="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/o7q1fAovQ1ecOSJmAWiv"><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/o7q1fAovQ1ecOSJmAWiv" alt="Arduino-RFM69HW-Verdrahtung" width="700" height="657" /></a> <p>Die Verdrahtung von Arduino und RFM69HW Quelle: https://electronichamsters.files.wordpress.com/2014/09/dd_basic.png</p></div>

```
Tipp:
Die Verbindungsdrähte und „Antenne“ des RFM69HW waren bereits angelötet (die Antenne ist für die 
Verwendung in einem Raum vermutlich redundant). Wir mussten also nur die Drähte des RFM69HW an 
den Arduino anschließen.
```

<h3>Software-Aufbau</h3><p>Die Arduino-Software lässt sich wie im <a href="https://www.arduino.cc/en/Guide/HomePage" name="Getting Started Guide">Getting Started Guide</a>  beschrieben installieren. Als nächstes kopiert man die Bibliothek-Verzeichnisse (RFM69 and SPIFlash) in das Arduino-Bibliotheken-Verzeichnis (Standard ist hierfür $home/Arduino/libraries (analog unter Windows)).</p><p>Die <a href="https://github.com/LowPowerLab/RFM69" name="RFM69 library">RFM69-Bibliothek</a>  hat auch entsprechende Beispiele (im Verzeichnis Examples).</p><p>Die Beispiele namens Gateway und Node sind bereits einsatzbereit. Versuche das Kompilieren: Öffne die Beispiel-Datei in der Arduino-Software und führe die Verifizieren-Funktion aus (der Knopf mit dem Häkchen-Zeichen oder im Menü unter Sketch-> Überprüfen/Kompilieren)</p><p>Code-Änderungen</p>

```
#define FREQUENCY RF69_433MHZ
//#define FREQUENCY RF69_868MHZ
//#define FREQUENCY RF69_915MHZ
```

<p>in</p>

```
//#define FREQUENCY RF69_433MHZ
#define FREQUENCY RF69_868MHZ
//#define FREQUENCY RF69_915MHZ
```

<p>Lade ein Beispiel auf jeweils einen Arduino und überprüfe die Funktion mit dem seriellen Monitor (Menü Werkzeuge->serieller Monitor) . Es sollten Textausgaben zu sehen sein.</p>

```
Notiz: 
Setze den baud-Wert des seriellen Monitors auf 115200 oder ändere diesen Wert in beiden Code-
Beispielen.

Wir haben das Gateway-Beipiel auf den SainSmart UNO und das Node-Beispiel auf den Seeeduiono 
hochgeladen. Das Hochladen auf den Seeeduiono hat seine Tücken. 
Man muss der Reset-Knopf während des Hochladens gedrückt halten und sofort nach Abschluss 
loslassen, sonst funktioniert es nicht. 
Wird der Reset-Knopf zu früh oder zu spät losgelassen, muss man den Vorgang wiederholen.
```

<p>Wenn beide Arduinos vorbereitet sind und eine Stromversorgung haben, sollte man nun auf dem seriellen Monitor sehen, dass der Gateway Daten vom Node empfängt.</p><h2>Ergebnis</h2><p>Trotz der einen oder anderen Hürde haben wir es geschafft, eine Verbindung zwischen Gateway und Node aufzubauen. Die Ausgabe des Node zeigte, dass gesendet wurde und die Ausgabe des Gateway, dass es auch empfangen wurde.</p><p>Somit haben wir den Ping-Teil des Zieles erreicht.</p><p>Nichtsdestotrotz haben wir es nicht geschafft, dass der Node eine Empfangsbestätigung vom Gateway empfing bzw. ausgab. Der Pong-Teil des Zieles wurde somit nicht erreicht.</p><div><a href="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8Luvxel1QVCu3cI9vef0"><img loading="lazy" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8Luvxel1QVCu3cI9vef0" alt="On-Scene Setup" width="700" height="525" /></a> <p>Aufbau am Platz</p></div><h2>Ausblick</h2><p>Erste Aufgabe für den nächsten Hackergarten Stuttgart wird es daher sein, das Pong zum Laufen zu bekommen. Außerdem haben wir uns ein neues Zeil ausgedacht, sozusagen eine Daseinsberechtigung für unseren Funkübertragungsaufbau. Da die Idee aus einem Heimautomatisierungs-Projekt stammt, ist es naheliegend, tatsächlich einen Hackergarten zu beschaffen und für diesen ein automatisches Bewässerungssystem zu entwickeln. Natürlich muss das System dann auch mittels verschlüsseltem Funk kommunizieren.</p><h2>Update</h2><p>Wir haben ein Hackergarten Github-Repo angelegt:<br /> <strong><a href="https://github.com/hackergarten-stuttgart/EWHA" target="_blank">hackergarten-stuttgart/EWHA</a> </strong></p><p>Es gibt ein Fortsetzungsprojekt:<br /> <strong><a href="http://pilhuhn.blogspot.de/2015/10/driving-servo-on-arduino-from-remote.html" target="_blank">Driving a Servo on Arduino from a remote Arduino over secured radio</a> </strong></p>

DIY leichtgewichtige verschlüsselte Funkübertragung

<p>The first hacker garden Stuttgart took place on the 23rd of July 2015. One of the hacks was a DIY encrypted lightweight radio transmitters ping-pong.</p><p>The idea originates from a home automation project from one of the hackers. Apparently there is a lack of encrypted radio transmission protocols, respectively the hardware and software components on the market. If you want something done right, you usually have to DIY.<br /> So the task for this hacker garden was to initiate a connection between a gateway and a node. And establish an encrypted ping-pong communication.</p><h2>Used Hardware</h2><p>Here is a list of the Hardware we used:</p><ul><li>1x Seeeduino v3.0</li><li>1x <a href="http://www.sainsmart.com/sainsmart-uno-r3-atmega328-au-development-board-compatible-with-arduino-uno-r3.html" name="SainSmart UNO R3">SainSmart UNO R3</a> </li><li>2x RFM69HW: -120dBm 433/868/915Mhz RF Transceiver Module</li><li>Small stuff like cables, soldering tin, …</li></ul>

```
Tip:
Mind that the RFM69HW is a 3.3V device, so your Arduino has to bring a 3.3v output, or you add an 
additional 3.3V power adaptor.
```

<h2>Used Software</h2><ul><li><a href="https://www.arduino.cc/en/Main/Software" name="Arduino Software">Arduino-Software</a> </li><li><a href="https://github.com/LowPowerLab/RFM69" name="RFM69 library for RFM69W and RFM69HW">RFM69 library for RFM69W and RFM69HW</a> </li><li><a href="https://github.com/LowPowerLab/SPIFlash" name="Arduino library for read/write access to SPI flash memory chips">Arduino library for read/write access to SPI flash memory chips</a> </li></ul>

```
Tip:
The Seeeduiono uses a FTDI USB chip so you should look at this how-to, in order to have the sufficient USB drivers.
```

<h2>Setup</h2><p>Since you can only show one Serial Monitor with the Arduino Software you should have another serial port monitor (e.g. <a href="http://freeware.the-meiers.org/">CoolTerm</a> ), another computer, or just switch from one Arduino to the other.</p>

```
Tip:
 We had two Macs so it was easy to hack in parallel.
```

<h3>Hardware Setup</h3><div><a href="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/o7q1fAovQ1ecOSJmAWiv"><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/o7q1fAovQ1ecOSJmAWiv" alt="Cable-Connection-Image" width="700" height="657" /></a> <p>The cable setup of the Arduinos and the radio transceivers<br />Source: https://electronichamsters.files.wordpress.com/2014/09/dd_basic.png</p></div>

```
Tip:
The connecting cables and antenna for the RFM69HW were already soldered on (you probably don't 
need the antenna for a setup in the same room). So we only had to connect the cables of the 
RFM69HW to the Arduino.
```

<h3>Software Setup</h3><p>Install the Arduino Software as described at this <a href="https://www.arduino.cc/en/Guide/HomePage" name="Getting Started Guide">Getting Started Guide</a> .<br /> Copy the library directories (RFM69 and SPIFlash) into the Arduino libraries directory. (Standard for the lib dir is $home/Arduino/libraries (analogly with Windows))</p><p>The <a href="https://github.com/LowPowerLab/RFM69" target="_blank">RFM69 library</a>  comes with some examples (in the Examples directory).</p><p>The Gateway and Node example are ready to go. Try to compile the examples:<br /> Open the example files in Arduino Software and use the Verify function (the button with the tick mark by menu Sketch->Verify/Compile).</p><p>Code-Changes:</p>

```
 #define FREQUENCY RF69_433MHZ
 //#define FREQUENCY RF69_868MHZ
 //#define FREQUENCY RF69_915MHZ
```

<p>to</p>

```
//#define FREQUENCY RF69_433MHZ
#define FREQUENCY RF69_868MHZ
//#define FREQUENCY RF69_915MHZ
```

<p>Upload one example on each Arduino and check if it is working by opening the Serial Monitor (menu Tools->Serial Monitor).<br /> You should see some text outputs.</p>

```
Note:
Set the baud of the Serial Monitor to 115200 or change it in the examples code.
We uploaded the Gateway example on the SainSmart UNO and the Node example on the Seeeduino.
The upload on the Seeeduino is a little tricky. You have to hold the reset button, then upload and just 
when finished uploading release the button. If you release the button too early/late the upload will fail 
and you'll have to start over.
If both Arduino setups are on power, you should see that the Gateway receives data from the node.
```

<h2>Result</h2><p>With some hurdles, we managed to establish a connection between Gateway and Node. The Node output showed that it was sending. And the Gateway output showed that it was receiving.<br /> So we managed to get a ping.<br /> Nonetheless we didn’t manage to get the Node to receive an acknowledge request of the Gateway. Hence the pong for the task failed.</p><div><a href="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8Luvxel1QVCu3cI9vef0"><img loading="lazy" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8Luvxel1QVCu3cI9vef0" alt="On-Scene Setup" width="700" height="525" /></a> <p>On-Scene Setup</p></div><h2>Lookout</h2><p>The first task for the next hacker garden will be to get the pong working.<br /> But we design-thought (I heard that design thinking is the new brainstorming) for another major task, one could say a purpose for this radio transmitter setup. Since our task at this hacker garden originates from a home automation project, it would seem natural to actually procure a hacker <em>garden</em> with an automatic irrigation system – of course communicating via an encrypted radio transmission.</p><h2>Update</h2><p>We created a github-repo for our hacker garden project:<br /> <strong><a href="https://github.com/hackergarten-stuttgart/EWHA" target="_blank">hackergarten-stuttgart/EWHA</a> </strong></p><p>There is a followup project:<br /> <strong><a href="http://pilhuhn.blogspot.de/2015/10/driving-servo-on-arduino-from-remote.html" target="_blank">Driving a Servo on Arduino from a remote Arduino over secured radio</a> </strong></p>

DIY encrypted lightweight radio transmission

Software Engineering, Software Consulting, Software Crafting, Team Effectiveness Consulting

Head of Marketing

Leiter Region Südwest

Rust – Einstieg

Rust – an introduction

Senior IT-Consultant

Senior IT Consultant

Office Manager Region Südwest

Market Lead Energy & Utilities

Senior Active Sourcerin

Ines Müller, Senior Active Sourcer, codecentric AG

Software Developer & Consultant

IT Consultant

Senior Industrial Solutions Developer and Consultant

<p>Eine populäre Methode, um REST APIs zu dokumentieren ist Swagger 2. Für Spring(-Boot)-Projekte bietet sich <a href="https://github.com/springfox/springfox" target="_blank">Springfox</a>  an. Springfox integriert sich recht nahtlos in ein Spring-Projekt und stellt für konfigurierte REST Endpoints eine Browser-basierte <a href="https://swagger.io/tools/swagger-ui/" target="_blank">Swagger UI</a>  Representation zur Verfügung. Mittels Annotations im Code können umfangreiche Details und Informationen zur API-Dokumentation hinzugefügt werden, z. B. erweiterte Informationen zu http-Statuscodes oder Beschreibungen zu einzelnen Feldern von Ressource-Modellen. Allerdings gibt es keine OOTB-Verbindung zwischen Swagger UI und der Spring-Security-Konfiguration. Dieser Artikel beschreibt eine Springfox-Swagger-UI-Erweiterung, um beide miteinander zu verbinden.</p><h2>Übersicht Spring Security und Spring REST Controller</h2><p>Durch die Verknüpfung von normalem Spring-Code mit Springfox API Annotations zur Generierung der Swagger-Dokumentation lässt sich ein altbekanntes Problem umgehen, nämlich dass Code und Dokumentation auseinanderlaufen und damit die Dokumentation häufig nicht dem aktuellen Code entspricht.</p><h3>Spring-Security-Beispiel</h3><p>Allerdings lässt sich mit Springfox die verwendete Spring-Security-Konfiguration nicht dokumentieren. Spring Security sichert per (Java-)Konfiguration ein REST-API ab und stellt eine Brücke zwischen Authentifizierung und Autorisierung her. Das folgende Code-Snippet beispielsweise sichert den REST-Endpoint „/user“ für GET- und POST-Zugriffe ab:</p><div>

```java5
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception {
        super.configure(httpSecurity);
 
        httpSecurity.csrf().disable();
        httpSecurity.httpBasic();
 
        httpSecurity.authorizeRequests()
            .antMatchers(HttpMethod.POST, "/user").hasRole("admin")
            .antMatchers(HttpMethod.GET, "/user/*").hasAnyRole("admin", "user");
 
        httpSecurity.authorizeRequests().anyRequest().fullyAuthenticated();
    }
}
```

</div><p>Die obige Spring-Security-Konfiguration definiert, dass die Ressource „user“ sowohl von Usern mit der Rolle „user“ als auch mit der Rolle „admin“ abgefragt (GET) werden darf, während der schreibende Zugriff (POST) auf dieselbe Ressource nur durch Nutzer mit der Rolle „admin“ erlaubt ist.</p><h3>Spring-REST-Controller-Beispiel</h3><p>Eine Spring-Security-Java-Konfiguration ist relativ einfach zu lesen und zu verwalten. Ein Problem ist aber, dass diese Config von der eigentlichen Ressource, also dem REST Endpoint, losgelöst ist:</p><div>

```java5
@RestController
public class MyRestController {
    @RequestMapping(method = RequestMethod.GET, value = "/user/{username}", produces = APPLICATION_JSON_VALUE)
    @ApiOperation("Get details of a user with the given username")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Details about the given user"),
            @ApiResponse(code = 401, message = "Cannot authenticate"),
    })
    public UserDTO getExampleData(@Valid
                                  @ApiParam("Non-empty username") @PathVariable(name = "username", required = true) String username) {
        /*
            Get your user resource somehow and return
         */
    }
    @PostMapping(value = "/user", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.CREATED)
    @ApiOperation("Create a new user or update an existing user (based on username)")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "User was successfully updated"),
            @ApiResponse(code = 201, message = "User was successfully created"),
            @ApiResponse(code = 401, message = "Cannot authenticate"),
    })
    public void createUser(@Valid @RequestBody UserDTO userDTO) {
        /*
            Save the user resource somehow
        */
    }
}
```

</div><p>Der hier dargestellte REST-Controller wird durch Springfox API Annotations dokumentiert (Springfox ist sehr viel mächtiger als hier dargestellt, siehe <a href="https://springfox.github.io/springfox/docs/current/" target="_blank">Springfox Reference Documentation</a> ). Ein Blick auf das generierte Swagger UI zeigt allerdings, dass die Spring-Security-Konfiguration aus der Klasse SecurityConfig nicht in die Dokumentation einfließt. D.h. es ist nicht ersichtlich, welche Ressource durch welche Rollen aufrufbar ist:</p><p><a href="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/ZZqPYzvTf6GQyPooW3Yc"><img width="700" height="987" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/ZZqPYzvTf6GQyPooW3Yc" alt="Standard Swagger UI" /></a> </p><p>Wie kann also Springfox so erweitert werden, dass die Spring-Security-Konfiguration automatisch Teil der Swagger-Dokumentation wird und damit eine höhere Kohäsion zwischen Implementierung und Dokumentation entsteht?</p><h2>Swagger-UI-Erweiterung für Spring Security</h2><p>Im Artikel <a href="/wissens-hub/blog/springfox-swagger-inkludieren-markdown" target="_blank">Springfox Swagger mit externem Markdown erweitern</a>  hat Markus Höfer von codecentric bereits dargestellt, wie einfach Springfox mit Custom Annotations erweitert werden kann. Darauf basierend entstand der hier beschriebene Lösungsweg, um Spring-Security-Rollen in das Swagger UI zu übernehmen.</p><p>Folgende grundlegende Schritte sind notwendig, um eine Custom Annotation für Springfox Swagger UI zu erstellen:</p><ol><li> Erzeugen einer Custom Annotation</li><li> Implementierung eines Custom Springfox OperationBuilderPlugins</li><li> Custom Annotation an alle REST-Controller Endpoints hinzufügen</li></ol><p>Weiterhin muss die Spring-Security-Konfiguration für die Springfox-Erweiterung „auslesbar“ gemacht werden, was im Folgenden zuerst beschrieben wird.</p><h3>Spring Security auslesbar machen</h3><p>Wie ein REST-API mit Spring Security gesichert werden kann, wurde bereits <a href="#spring-security-beispiel">oben kurz dargestellt</a> .</p><p>Spring Security verwendet Ant-Matcher Pattern, um http-Methoden und URL-Pfade zu spezifizieren, auf die definierte Rollen zugreifen dürfen. Diese Konfiguration ist jedoch „write-only“, d.h. die Klasse <em>HttpSecurity</em> (genauer gesagt die Klasse <code>ExpressionUrlAuthorizationConfigurer.ExpressionInterceptUrlRegistry</code> aus dem Package <code>org.springframework.security.config.annotation.web.configurers</code>) lässt nicht zu, dass die Konfiguration der Ant-Matcher wieder ausgelesen wird. Das ist aber für unseren Use Case notwendig, denn wir wollen genau diese Information in unserer Swagger-Doku haben, müssen sie also auslesen können. Die vorgeschlagene Lösung verwaltet daher die Ant-Matcher-Konfiguration in einer eigenständigen Klasse namens <code>HttpMethodResourceAntMatchers</code>, die sowohl der HttpSecurity Configuration als auch der Swagger-Doku als Spring Component zur Verfügung steht:</p><div>

```java5
public class HttpMethodResourceAntMatchers {
    Logger logger = LoggerFactory.getLogger(HttpMethodResourceAntMatchers.class);
    // list of all defined matchers
    List matcherList = new ArrayList<>();
    /**
     * Applies all existing Matchers to the provided httpSecurity object as .authorizeRequest().antMatchers().hasAnyRole()
     * @param httpSecurity
     * @throws Exception
     */
    public void configure(org.springframework.security.config.annotation.web.builders.HttpSecurity httpSecurity) throws Exception {
        for (HttpMethodResourceAntMatcher matcher : this.matcherList) {
            httpSecurity.authorizeRequests().antMatchers(matcher.getMethod(), matcher.getAntPattern()).hasAnyRole(matcher.getRoles());
        }
    }
    /**
     * Add a new Matcher with HttpMethod and URL-Path
     * @param method
     * @param antPattern
     * @return
     */
    public Role antMatchers(org.springframework.http.HttpMethod method, String antPattern) {
        // create a new matcher
        HttpMethodResourceAntMatcher matcher = new HttpMethodResourceAntMatcher(method, antPattern);
        // add matcher to list of matchers
        this.matcherList.add(matcher);
        // return a Role wrapper object, which forces the user to add the role(s) to the matcher
        Role role = new Role(matcher, this);
        return role;
    }
    /**
     * Helper class for a builder-like creation pattern
     */
    public class Role {
        HttpMethodResourceAntMatcher matcher;
        HttpMethodResourceAntMatchers matchers;
 
        public Role(HttpMethodResourceAntMatcher matcher, HttpMethodResourceAntMatchers matchers) {
            this.matcher = matcher;
            this.matchers = matchers;
        }
        /**
         * Define which role has access to the given resource identified by the Ant-Matcher
         * @param role
         * @return
         */
        public HttpMethodResourceAntMatchers hasRole(String role) {
            matcher.setRoles(role);
            return matchers;
        }
        /**
         * Add a list of roles which have access to the given resource identified by the Ant-Matcher
         * @param roles
         * @return
         */
        public HttpMethodResourceAntMatchers hasAnyRole(String... roles) {
            matcher.setRoles(roles);
            return matchers;
        }
    }
}
```

</div><p>Die Klasse <code>HttpMethodResourceAntMatchers</code> imitiert die Spring HttpSecurity <code>antMatchers()</code> und <code>hasRole()</code>. Die hier referenzierte Klasse <code>HttpMethodResourceAntMatcher</code> ist ein einfacher Pojo mit den Membern „httpMethod“, „antPattern“ und „roles“.</p><p>Die eigentliche Konfiguration der Matcher mithilfe der Klasse <code>HttpMethodResourceAntMatchers</code> findet durch die Custom Spring Component <code>MatchersSecurityConfiguration</code> statt:</p><div>

```java5
@Component
public class MatchersSecurityConfiguration {
 
    private HttpMethodResourceAntMatchers matchers;
 
    /**
     * Returns all http matchers
     * @return
     */
    public HttpMethodResourceAntMatchers getMatchers() {
        if (matchers == null) {
            matchers = new HttpMethodResourceAntMatchers();
            matchers.antMatchers(HttpMethod.POST, "/user").hasRole("admin")
                    .antMatchers(HttpMethod.GET, "/user/*").hasAnyRole("admin", "user");
        }
        return matchers;
    }
}
```

</div><p><code>MatchersSecurityConfiguration</code> wird sowohl in die Spring Security Config injiziert als auch in die nachfolgende Swagger-Hilfsklasse für unsere Custom Annotation.</p><p>Damit kann unsere Spring Security Config folgendermaßen angepasst werden:</p><div>

```java5
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
 
    @Autowired
    private MatchersSecurityConfiguration matchersSecurityConfiguration;
 
    @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception {
        super.configure(httpSecurity);
 
        httpSecurity.csrf().disable();
        httpSecurity.httpBasic();
        // add matchers for REST API to httpSecurity
        this.matchersSecurityConfiguration.getMatchers().configure(httpSecurity);
 
        httpSecurity.authorizeRequests().anyRequest().fullyAuthenticated();
    }
}
```

</div><p>Nachdem wir die Spring-Security-Konfiguration angepasst haben, müssen die Swagger Annotation und die Springfox-Erweiterung erstellt werden.</p><h3>Custom Annotation</h3><p>Für unseren Use Case erstellen wir die Custom API Annotation <code>ApiRoleAccessNotes</code>:</p><div>

```java5
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiRoleAccessNotes {
}
```

</div><p>Die Annotation hat keinerlei Parameter, sie ist ein Marker für unser <code>OperationBuilderPlugin</code>.</p><h2>Custom Springfox OperationBuilderPlugin</h2><p>Damit die oben definierte Annotation verwendet werden kann, muss das <code>OperationBuilderPlugin</code> Interface als Spring Component implementiert werden. Die <em>apply</em>-Methode wird vom Springfox <code>DocumentationPluginsManager</code> für jede REST-Resource im Classpath aufgerufen:</p><div>

```java5
@Component
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER)
public class OperationNotesResourcesReader implements springfox.documentation.spi.service.OperationBuilderPlugin {
    private final DescriptionResolver descriptions;
 
    @Autowired
    private MatchersSecurityConfiguration matchersSecurityConfiguration;
 
    final static Logger logger = LoggerFactory.getLogger(OperationNotesResourcesReader.class);
 
    @Autowired
    public OperationNotesResourcesReader(DescriptionResolver descriptions) {
        this.descriptions = descriptions;
    }
 
    @Override
    public void apply(OperationContext context) {
        try {
            Optional methodAnnotation = context.findAnnotation(ApiRoleAccessNotes.class);
            if ( !methodAnnotation.isPresent() || this.matchersSecurityConfiguration == null) {
                // the REST Resource does not have the @ApiRoleAccessNotes annotation --> ignore
                return;
            }
            String apiRoleAccessNoteText = "Accessible by users having one of the following roles: ";
            HttpMethodResourceAntMatchers matchers = matchersSecurityConfiguration.getMatchers();
            // get all configured ant-matchers and try to match with the current REST resource
            for (HttpMethodResourceAntMatcher matcher : matchers.matcherList) {
                // get the RequestMapping annotation, which contains the http-method
                Optional requestMappingOptional = context.findAnnotation(RequestMapping.class);
                if (matcher.getMethod() == getHttpMethod(requestMappingOptional)) {
                    AntPathMatcher antPathMatcher = new AntPathMatcher();
                    String path = context.requestMappingPattern();
                    if (path == null) {
                        continue;
                    }
                    boolean matches = antPathMatcher.match(matcher.getAntPattern(), path);
                    if (matches) {
                        // we found a match for both http-method and URL-path, get the roles
                        // add the roles to the notes. Use Markdown notation to create a list
                        apiRoleAccessNoteText = apiRoleAccessNoteText + "\n * " +  String.join("\n * ", matcher.getRoles());
                    }
                }
 
            }
            // add the note text to the Swagger UI
            context.operationBuilder().notes(descriptions.resolve(apiRoleAccessNoteText));
        } catch (Exception e) {
            logger.error("Error when creating swagger documentation for security roles: " + e);
        }
    }
 
    private HttpMethod getHttpMethod(Optional requestMappingOptional) {
        if (!requestMappingOptional.isPresent()) return null;
        if (requestMappingOptional.get().method() == null || requestMappingOptional.get().method()[0] == null)
            return null;
        RequestMethod requestMethod = requestMappingOptional.get().method()[0];
        switch (requestMethod) {
            case GET:
                return HttpMethod.GET;
            case PUT:
                return HttpMethod.PUT;
            case POST:
                return HttpMethod.POST;
            case DELETE:
                return HttpMethod.DELETE;
        }
        return null;
    }
 
    @Override
    public boolean supports(DocumentationType delimiter) {
        return SwaggerPluginSupport.pluginDoesApply(delimiter);
    }
}
```

</div><p>Innerhalb der Klasse wird geprüft, ob die aktuell von Springfox verarbeitete Ressource unsere <code>ApiRoleAccessNotes</code>-Annotation besitzt. Ist dies der Fall, dann holen wir uns alle Spring Security Matcher und prüfen, welche davon auf die die aktuelle Ressource passen – sowohl in Bezug auf die Http-Methode also auch auf den konfigurierten URL-Path.</p><h3>Custom Annotion @ REST Controller</h3><p>Abschließend muss die Custom Annotation <code>@ApiRoleAccessNotes</code> zu allen REST-Ressourcen hinzugefügt werden, für die wir im Swagger UI die konfigurierten Rollen sehen wollen:</p><div>

```java5
@RestController
public class MyRestController {
    @RequestMapping(method = RequestMethod.GET, value = "/user/{username}", produces = APPLICATION_JSON_VALUE)
    @ApiOperation("Get details of a user with the given username")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Details about the given user"),
            @ApiResponse(code = 401, message = "Cannot authenticate"),
    })
    @ApiRoleAccessNotes
    public UserDTO getExampleData(@Valid
                                  @ApiParam("Non-empty username") @PathVariable(name = "username", required = true) String username) {
        /*
            Get your user resource somehow and return
         */
    }
 
    @PostMapping(value = "/user", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.CREATED)
    @ApiOperation("Create a new user or update an existing user (based on username)")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "User was successfully updated"),
            @ApiResponse(code = 200, message = "User was successfully created"),
            @ApiResponse(code = 401, message = "Cannot authenticate"),
    })
    @ApiRoleAccessNotes
    public void createUser(@Valid @RequestBody UserDTO userDTO) {
        /*
            Save the user resource somehow
        */
    }
}
```

</div><p>Im Swagger UI sieht das Ganze dann folgendermaßen aus:</p><p><a href="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/N5nAu6QyRGCswUf6Mrmp"><img loading="lazy" width="634" height="916" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/N5nAu6QyRGCswUf6Mrmp" alt="Custom Swagger UI" /></a> </p><h2>Fazit</h2><p>Mit ein paar wenigen Kniffen haben wir es geschafft, dass unsere Dokumentation wieder etwas näher an den Sourcecode gerückt ist. Der Sourcecode steht unter <a href="https://github.com/HenningWaack/SpringFoxSwaggerExtensionDemo" target="_blank">https://github.com/HenningWaack/SpringFoxSwaggerExtensionDemo</a>  zur Verfügung. Viel Spaß damit, und ich freue mich über alle Kommentare zu diesem Post!</p>

Springfox Swagger Extensions für Spring Security

<p><b>BigQuery can help with building an ML system for production with a short time to market.</b></p><ul><li><b>Follow industry standards.</b><span> Agile methods, the MLOps framework and focus on an MVP are helpful.</span></li><li><b>Model improvement is not everything.</b><span> A good model evaluation as well as versioning and metadata tracking are worth the effort.</span></li><li><b>BigQuery also has downsides.</b><span> The API and slot management can be a hindrance at first.</span></li></ul><p><span>In my bachelor thesis I examined how medium-sized companies can effectively set up their own machine learning (ML) system using limited resources.</span><span><br /> </span><span>The reason for that was, that in 2020, despite the coronavirus pandemic, 71% of companies increased their investments in ML <a href="https://info.algorithmia.com/hubfs/2020/Reports/2021-Trends-in-ML/Algorithmia_2021_enterprise_ML_trends.pdf?hsLang=en-us" target="_blank">[1]</a> . </span><span> However, the resources of a medium-sized company remain finite. In addition, only 53% of ML proof of concepts (POC) were deployed in production and realised their promised value between 2018 and 2020, according to Gartner  <a href="https://www.gartner.com/en/documents/3987446/accelerating-ai-deployments-paths-of-least-resistance" target="_blank">[2]</a> </span><span>.</span></p><p><span>In the context of my thesis, I cooperated with the Mosecker GmbH, a leading family-owned, medium-sized wholesale company for domestic appliances, their core business being customer satisfaction rather than IT. We carried out a project to develop a production-ready ML system prototype, to test a combination of agile methods and the MLOps framework as a development approach. </span></p><p><span>The approach proved to be helpful.</span><span><br /> </span><span>However, in the following, I will focus on the usage of the managed cloud service </span><b>BigQuery ML</b><span> we used as the basis for the ML system. I will first introduce the project and system in general and then go into detail about a few particularities.</span></p><h2><b>The Project</b></h2><p><span>The project’s goal was to create a recommendations system prototype for personalized product recommendations in the web store of Mosecker in less than ten weeks. </span><span>The prototype should also be suitable for use in production. To bring the idea to the market as quickly as possible and validate it.</span></p><p><span>For the project, delivery data between 01.01.2019 and 15.09.2021 was made available. </span><span>These included</span></p><ul><li><span>a total of 4,823,891 transactions </span></li><li><span>5,897 different customers </span></li><li><span>910,002 individual items</span></li></ul><h3><b>System Setup</b></h3><p><span>Since one of the primary conditions is to create the prototype with the least resources and effort possible, all required resources were sourced from the cloud right from the start to avoid ramp-up costs and delays due to hardware provisioning and configuration.<br /> </span><span>Another advantage of the cloud strategy is the on-demand use and billing of storage and computing resources. This makes it possible to easily scale up the prototype at a later time. </span></p><p><span>I mainly used the </span><b>BigQuery</b><span> service and its built-in ML capabilities from the Google Cloud Platform (GCP) for this project, as I had previously used it for a similar use case. At the moment of writing, the first processed terabyte of every month was free, which meant even fewer costs. </span><span>For a detailed description of how to create a recommendation model with BigQuery ML, I recommend two blog posts from my codecentric colleagues, Timo Böhm and Niklas Haas. The first  <a href="/wissens-hub/blog/bigquery-ml-schnelles-training-recommendation-modell" target="_blank">[3]</a> </span><span> is about the technical part; the second <a href="/wissens-hub/blog/kuerzere-time-to-market-fuer-ml-modelle-durch-googles-bigquery-ml" target="_blank">[4]</a>  </span><span>is about the business perspective. </span></p><p><span>To complete the system with metadata tracking, I used the open-source tool MLflow. </span><span>In concept, the ML system then consisted of three parts:</span></p><ol><li><span>BigQuery in GCP to process the data, train and evaluate the model, and create the recommendations.</span></li><li><span>A Docker image as a pipeline to be executed (locally), which manages and monitors the individual steps of the process.</span></li><li><span>MLflow, collecting various metadata about the training run and the created model during execution, these are then comparably presented in a web UI.</span></li></ol><p><span>Figure 1 shows the interaction of the components during execution.</span></p><div><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/lwbZrxCdTsu9r9WVB4Tv" alt="Schematic of training pipeline" width="1024" height="332" /><p>Figure 1: Schematic of training pipeline, communication between pipeline and BigQuery</p></div><p><span>This sums up to a single GCP project and two images, one to run the pipeline, the other to host the MLflow Web UI.<br /> </span><span>The training data is provided as CSV files in a mounted volume.</span></p><p><span>I have to note here that it was not the project’s scope to provide continuous monitoring, though this is in general a crucial step when following industry-standard MLOps principles  <a href="https://services.google.com/fh/files/misc/practitioners_guide_to_mlops_whitepaper.pdf" target="_blank">[5]</a> . </span></p><h3><b>Pipeline steps</b></h3><p><span>The pipeline is separated into five steps:</span></p><ol><li><ol><li><b>Data Import</b><span>: Upload CSV files to BigQuery</span></li><li><b>Data preparation</b><span>: Data cleaning and creation of the training dataset</span></li><li><b>Model training: </b><span>Creating the model and extraction of the recommendation </span></li><li><b>Model evaluation: </b><span>Validating the model based on mathematical methods</span></li><li><b>Prediction serving: </b><span>Exporting the top recommendations per customer in a CSV file</span></li></ol></li></ol><p><span>The MLOps white paper of Google <a href="https://services.google.com/fh/files/misc/practitioners_guide_to_mlops_whitepaper.pdf" target="_blank">[5]</a> </span><span> served as a template for the structure. </span><span>It was then adapted to the project’s needs and technical requirements of the BigQuery ML service. This resulted in the pipeline steps described above.</span></p><h2><b>Implementation peculiarities and beneficial factors</b></h2><p><span>The use of BigQuery as an integral part of the system presented some challenges. But I also want to highlight some beneficial factors for completing the project.</span></p><h3><b>Start simple with a baseline model</b></h3><p><span>One of them is to start with a minimal baseline model. </span><span>Even though the idea of technical cut-through is not new, I want to highlight it here. </span><span>Since BigQuery ML uses SQL to train ML models, creating a baseline model with default values is easy and fast.  </span><span>This allowed me to focus more on creating the system in the first place, to make a technical cut-through including recommendation serving and simplifying the further improvement of the model.</span></p><p><span>Note:<br /> </span><span>Using an established ML use case made the development of the model easier, which is why I was able to focus on the technical cut-through. However, it might make more sense to focus on the model first in less common use cases, where you can not rely on a broad knowledge base for the model.</span></p><h3><b>Evaluation of the model in BigQuery ML</b></h3><p><span>One of the biggest challenges for me was to evaluate the created model. </span><span>BigQuery ML does evaluate the model automatically during its creation. But Google does not provide more detailed information about the metric calculation or implementation, making it a black box. </span><span>For this reason, I implemented the calculation of the </span><b>mean average precision@k</b><span> (mAP@k) <a href="https://nlp.stanford.edu/IR-book/pdf/irbookonlinereading.pdf" target="_blank">[6]</a>  </span><span>myself. You can find the SQL statement in this gist  <a href="https://gist.github.com/SputnikTea/a8b8c258d603826140b0f373fd837c30" target="_blank">[7]</a> </span><span>.</span></p><p><span>During the project, I realised the mAP@k exhibited an unexpected behaviour in some edge cases.<br /> </span><span>As soon as the remaining recommendations of a query were all negative (0), these were no longer considered in the precision calculation, as seen in figure 2. For this reason, I designed the mean Precision (mP@k) and implemented it in the project. Here, every recommendation in a query is included in the precision, regardless of being positive or negative, as seen in figure 3.</span></p><div><img loading="lazy" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/eSYVD6nCSWK66f0v4fLA" alt="Calculation of mean average precision@k" width="1024" height="317" /><p>Figure 2: Mean average precision@k, common case and edge case</p></div><div><img loading="lazy" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/jH6za1CQBe4Srx1MNZYg" alt="Calculation of mean precision@k" width="1024" height="317" /><p>Figure 3: Mean precision@k, common case and edge case</p></div><p><span>If this explanation was too short, I recommend this more detailed article <a href="https://towardsdatascience.com/breaking-down-mean-average-precision-map-ae462f623a52" target="_blank">[8]</a>  </span><span>by Ren Jie Tan. </span><span>For evaluating the model, I preferred to use the mP@k because I find it more understandable and thus closer to reality. The SQL statements for calculating the metrics can be found in this gist <a href="https://gist.github.com/SputnikTea/a8b8c258d603826140b0f373fd837c30" target="_blank">[7]</a> . </span></p><h3><b>Master the slots</b></h3><p><span>As much as the cloud can save costs, it can also cause them, if you are not careful. </span><span>Particular caution is required when booking computing resources in BigQuery, so-called slots <a href="https://cloud.google.com/bigquery/docs/slots" target="_blank">[9]</a> .</span><span> These must be used for training a matrix factorisation model; other algorithms can also be used with on-demand resources.<br /> The minimum slot amount (100) costs 4.80€/hour in the Netherlands. A model training for our data usually took only 20 to 30 minutes, so the costs were manageable. </span><span>However, booking (managing) the slots is only possible via the web interface, SQL or the CLI of the cloud SDK. Although I have automated the step in the pipeline using SQL, I wanted to make sure that the monetary damage is limited in case of an error. </span></p><p>Therefore I used the cloud scheduler and a cloud function to regularly drop all slots at midnight. Fortunately, dropping the slots is also possible in the Python client library. The cloud function code and CLI commands for the scheduler can be found in this gist <a href="https://gist.github.com/SputnikTea/333a84adf2c2f97ec43a5ab0f5621430" target="_blank"><span>[10]</span></a> . <span>In retrospect, I noticed that one could have alternatively used a scheduled query. But this might complicate the integration into a monitoring system.</span></p><h3><b>Tracking metadata with MLflow</b></h3><p><span>A month into the project, I lost track of the model versions and their performance. </span><span>Therefore, I included MLflow tracking <a href="https://www.mlflow.org/docs/latest/tracking.html" target="_blank">[11]</a>  </span><span>into the pipeline and used its web UI to compare the models.</span><span><br /> </span><span>Doing this, following things were useful:</span></p><ul><li><span>logging the SQL queries with `log_text()` for debugging</span></li><li><span>saving the pipeline YAML configuration as a file artefact with `log_artifact()`</span></li><li><span>using dataset IDs as model version indicators and table prefixes for different runs</span></li></ul><div><img loading="lazy" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/EMXubP0R5GLJVUZDvtWz" alt="MLflow UI, comparing two runs" width="1024" height="358" /><p>Figure 4: Example for comparing two runs in MLflow</p></div><p><span>I should mention that BigQuery ML is intended for the fast testing of model ideas by data analysts. Its use as an ML system is not intended, so features like metadata tracking or a proper client API are (currently) missing.<br /> </span><span>For ML systems, Google intends the use of Vertex AI, but this has a steep learning curve, especially for a beginner with a small project. AutoML systems, on the other hand, were very limiting in their configuration.<br /> </span><span>By the declarative work with SQL, BigQuery ML offered just the right amount of simplification and freedom to create the prototype according to my needs. Unfortunately, without a proper API, but the use of SQL queries had its own advantages. By working declaratively, there were hardly any bugs in the data transformation part.</span></p><h2><b>Project Results</b></h2><p><span>After eight weeks of development, the prototype has fulfilled all basic requirements:</span></p><ul><li><span>Creation and serving of a new model with one command</span></li><li><span>Relevant recommendations</span></li><li><span>Tracking of metadata</span></li></ul><p><span>In addition, the model did not recommend in majority previously bought items. Instead, also new items were recommended, which the stakeholders evaluated as reasonable.</span></p><div><img loading="lazy" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/3a59nQ82Toi19w5arQT8" alt="Model quality metrics by iteration" width="1024" height="633" /><p>Figure 5: Model quality by different metrics in the course of the project</p></div><p><span>Figure 5 shows the different model quality metrics in the course of the project, as well as their various results. For more information on the discrepancy between offline evaluation and user validation, I recommend this paper <a href="https://arxiv.org/pdf/1908.08328.pdf" target="_blank">[12]</a>  </span><span>by Dietmar Jannach.<br /> </span><span>The collection of the Ambassador User Validation, which was the key metric for the project, was facilitated by the completed ML system. </span></p><h2><b>Conclusion</b></h2><p><span>BigQuery ML is not intended to be an ML system; this becomes apparent when you want to use it in a script. But it reduces a lot of complexity to simple SQL statements without taking too much freedom in the model configuration. This makes creating a minimal viable product or prototype fast and easy.</span></p><p><span>The mentioned challenges in creating an ML system, like slot management or model evaluation and SQL calculations, are a hindrance. But for me, especially for smaller projects, they are made up for by ease of use and simultaneous freedom.</span></p><p><span>In the end, BigQuery did the job. It enabled me to build a machine learning system prototype with a continuous training pipeline, metadata tracking and prediction serving within eight weeks.</span></p><h2><b>Acknowledgements</b></h2><p><span>A huge thanks goes to Holger Sickmann and Fabrice Lepach at the Mosecker GmbH for making this project possible by providing the data and insight domain knowledge.</span><span><br /> </span><span>I also want to thank my supervisors, Michael Bücker at the FH Münster and Niklas Haas from codecentric, for keeping me on track and helping me with all my questions.</span></p>

BigQuery to the rescue: How to prototype an ML system for a medium-sized wholesale company in the Google Cloud

Developer

In der heutigen schnelllebigen und datengesteuerten Welt stehen Unternehmen vor einer zunehmend komplexen Herausforderung: Wie können Datenschnittstellen so gestaltet, implementiert und verwaltet werden, dass sie sowohl den unmittelbaren betrieblichen Anforderungen als auch den langfristigen strategischen Unternehmenszielen gerecht werden? Eine Datenschnittstelle ist ein definierter Verbindungspunkt, über den Daten zwischen Systemen, Anwendungen oder Komponenten ausgetauscht werden. Sie legt die Regeln, Formate und Protokolle fest, die für eine reibungslose Kommunikation und Interoperabilität erforderlich sind, und bildet das Rückgrat moderner Datenökosysteme.

Die Mehrheit der Unternehmen hat erkannt, dass Daten eine zentrale Rolle bei der Entscheidungsfindung spielen, Innovationen fördern und Wettbewerbsvorteile schaffen. Allerdings sind die vielfältigen Möglichkeiten zur Gestaltung von Datenschnittstellen oft schwer zu durchschauen, insbesondere für Softwarearchitekten, die die Kluft zwischen technischen Lösungen und Geschäftsergebnissen überbrücken müssen.

Hier kommt das Data Interface Quadrants (DIQs) Framework als transformatives Werkzeug ins Spiel. Die DIQs bieten einen strukturierten und visuellen Ansatz zur Analyse und Kategorisierung von Datenschnittstellen, der Architekten, Entwicklungsteams und Entscheidungsträgern hilft, die Komplexität zu reduzieren. Durch die Umwandlung der Komplexität von Datenschnittstellen in ein intuitives Format ermöglichen die DIQs wertvolle Einblicke, die eine bessere strategische Ausrichtung und fundierte Entscheidungen unterstützen.

In diesem Blog-Beitrag werden wir das Potenzial und den Wert der DIQs aus zwei Perspektiven betrachten: aus der Sicht des Unternehmensarchitekten, der sich auf die langfristige Unternehmensstrategie konzentriert, und aus der Sicht des Lösungsarchitekten, der sich mit projektspezifischen Implementierungsproblemen auseinandersetzt. Diese beiden Blickwinkel zeigen, wie DIQs eine effektive Zusammenarbeit fördern, um robuste und zukunftssichere Datenökosysteme zu schaffen und bestehende Systeme zu modernisieren. DIQs sind mehr als nur ein Diagramm – sie dienen als Kompass für die Entscheidungen und Kompromisse, die beim Design von Datenschnittstellen getroffen werden müssen.

## Einführung in die DIQs

![data-interface-quadrants-plain.jpg](https://media.graphassets.com/ojiHNTPMR7uzJZM3aCte)

Die DIQs bieten eine strukturierte Methode zur Kategorisierung von Datenschnittstellen anhand zweier Hauptdimensionen: dem Umfang der Datenverarbeitung und der Anzahl der Nutzerinnen und Nutzer. Die horizontale Achse der DIQs zeigt den Grad der Datenaggregation oder -transformation. Auf der linken Seite werden Rohdaten dargestellt, die kaum oder gar nicht umgewandelt werden. Diese sind besonders für Anwendungsfälle geeignet, die Basisdaten in ihrer ursprünglichen Form benötigen. Auf der rechten Seite hingegen werden aggregierte oder transformierte Daten dargestellt, die spezifische Anwendungsfälle unterstützen oder erweiterte Funktionen auf Service-Ebene bieten.

Die Komplexität der Datenverarbeitung steigt beim Übergang von Rohdaten zu aggregierten oder transformierten Daten. Rohdaten erfordern nur minimale Eingriffe und sind in der Regel schneller verfügbar, jedoch müssen die Nutzerinnen und Nutzer möglicherweise mehr Aufwand betreiben, um aussagekräftige Erkenntnisse daraus zu gewinnen. Im Gegensatz dazu erfordern aggregierte oder transformierte Daten zusätzliche Verarbeitungsschritte, wie die Kombination von Datensätzen, die Anwendung von Geschäftslogik oder die Anpassung der Daten an spezifische Anwendungsfälle. Obwohl dies die Erstellung und Pflege der Schnittstelle komplexer macht, kann es den Aufwand für die Nutzerinnen und Nutzer erheblich reduzieren und die Daten sofort für ihre Bedürfnisse nutzbar machen.

Die vertikale Achse der DIQs zeigt die Anzahl der Konsumenten, die mit den Daten interagieren. Im unteren Bereich liegt der Fokus auf produktinternen oder anwendungsspezifischen Schnittstellen, die in der Regel von einem einzigen Team oder einer klar definierten technischen Zielgruppe mit gemeinsamen Fachkenntnissen genutzt werden. Im oberen Bereich der DIQs hingegen werden externe und wiederverwendbare Schnittstellen dargestellt, die für mehrere Teams und verschiedene Zielgruppen konzipiert sind. Diese Zielgruppen können Personen mit unterschiedlichen technischen Kenntnissen oder sogar unbekannte Konsumenten umfassen.

Die beiden Achsen erzeugen vier Quadranten, von denen jeder eine bestimmte Art von Datenschnittstelle repräsentiert. Der Quadrant **Data Link** unten links steht für Rohdatenschnittstellen, die innerhalb eines einzelnen Produkts oder Teams verwendet werden. Diese Schnittstellen sind einfach und direkt, erfordern oft nur minimale Transformation und richten sich hauptsächlich an technische Zielgruppen mit klaren, gemeinsamen Anforderungen. Der Quadrant **Backend for Frontend (BFF)** unten rechts umfasst anwendungsspezifische Schnittstellen, die aggregierte oder transformierte Daten bereitstellen. Diese Schnittstellen sind auf spezifische Anwendungsbedürfnisse zugeschnitten und optimiert für Effizienz innerhalb eines einzelnen Produkts oder Teamkontexts. Entwicklungsteams entwerfen und implementieren beide Arten von Schnittstellen mit einem starken Fokus auf die Technologie.

Der Quadrant **Platform Data Product** oben links repräsentiert Rohdatenschnittstellen, die extern und wiederverwendbar sind. Diese Schnittstellen stellen grundlegende Daten in ihrer ursprünglichen Form einem breiten Publikum zur Verfügung, einschließlich unbekannter Konsumenten und Personen mit unterschiedlichem technischen Hintergrund. Hier stehen Wiederverwendbarkeit und Skalierbarkeit anstatt Spezifität im Vordergrund. Der Quadrant **Composition Service** oben rechts umfasst externe und wiederverwendbare Schnittstellen, die aggregierte und transformierte Daten bereitstellen. Diese Schnittstellen sind für verschiedene Anwendungsfälle konzipiert und werden von mehreren Teams genutzt. Ihre Erstellung und Pflege sind daher am komplexesten, gleichzeitig bieten sie jedoch die größte Vielseitigkeit für die Bedürfnisse des Unternehmens. Das breite Publikum erfordert von den Entwicklungsteams, beide Arten von Schnittstellen so zu gestalten und zu implementieren, dass der Fokus auf den geschäftlichen Anforderungen liegt und nicht auf der Technologie.

## Die Auswirkungen eines API-First-Geschäftsmodells

Wenn Unternehmen eine API-First-Strategie verfolgen, werden APIs zu einem zentralen Bestandteil ihres Geschäftsmodells. Dadurch verlagert sich der Fokus für Datenschnittstellen zunehmend auf die oberen Quadranten der DIQs. Anstatt produktinterne und anwendungsspezifische Schnittstellen zu entwickeln, müssen sich die Entwicklungsteams darauf konzentrieren, mehr externe und wiederverwendbare Schnittstellen für ein größeres Publikum zu erstellen, was zu höheren geschäftlichen Auswirkungen führt. Wenn die Teams bisher hauptsächlich **Backend for Frontend**-Schnittstellen erstellt haben, fehlt ihnen möglicherweise das Wissen, um einen erfolgreichen **Composition Service** zu entwickeln, der auf geschäftliche Auswirkungen abzielt. Enabling und Platform Teams können die Entwicklungsteams dabei unterstützen, den Übergang der APIs von rein technischen Schnittstellen zu geschäftsrelevanten Produkten zu vollziehen. Die DIQs helfen, solche strategischen Entscheidungen und ihre Auswirkungen auf das Design von Datenschnittstellen zu visualisieren.

![data-interface-quadrants-api-first.jpg](https://media.graphassets.com/YzoIBqRdT2z3FPXec4Dm)

## Unternehmensarchitekten: Die DIQs als strategische Linse

Unternehmensarchitekten agieren an der Schnittstelle von Geschäftsstrategie und technologischer Umsetzung und prägen damit auch die übergreifende Datenarchitektur. Die DIQs geben ihnen eine ganzheitliche Perspektive und ermöglichen eine strategische Übersicht, die die Kluft zwischen organisatorischen Zielen und technischen Realitäten überbrückt.

Mit Hilfe der DIQs können Unternehmensarchitekten Schnittstellen kategorisieren und bewerten sowie Investitionen dort priorisieren, wo sie am wichtigsten sind. Produktinterne und anwendungsspezifische Schnittstellen, die aggregierte oder transformierte Daten bereitstellen, können beispielsweise die Skalierbarkeit verbessern. Externe und wiederverwendbare Schnittstellen, die Rohdaten bereitstellen, bieten Optimierungsmöglichkeiten, da sie nur minimale Datenverarbeitung erfordern, aber aufgrund ihrer breiten Zielgruppe einen großen Einfluss auf das Unternehmen haben. Die DIQs helfen auch dabei, Engpässe und redundante Systeme zu identifizieren und unterstützen die Bemühungen zur Rationalisierung von Prozessen und Verbesserung der Integration.

Die DIQs dienen auch als Kommunikationsinstrument, indem sie Datenschnittstellen in einem klaren, visuellen Format darstellen. Unternehmensarchitekten können damit Diskussionen mit Stakeholdern erleichtern und technische Initiativen mit den umfassenderen Geschäftszielen in Einklang bringen. In Projekten zur digitalen Transformation helfen die DIQs, Schnittstellen zu identifizieren, die für eine Neugestaltung oder Investitionen geeignet sind. Dies stellt sicher, dass die heutigen Entscheidungen das zukünftige Wachstum unterstützen. Zudem können Unternehmensarchitekten die Entwicklungsteams erkennen, die mehr Unterstützung von Enabling und Platform Teams benötigen, um die Neugestaltung und Investitionen erfolgreich umzusetzen.

## Lösungsarchitekten: Eine Brücke zwischen Strategie und Ausführung

Lösungsarchitekten setzen Ideen um, indem sie Systeme entwerfen, die den unmittelbaren Projektanforderungen gerecht werden und gleichzeitig umfassende Architekturprinzipien berücksichtigen. Die DIQs unterstützen sie dabei, konkurrierende Prioritäten zu bewältigen und bieten eine strukturierte Sichtweise, um Datenschnittstellen effektiv zu bewerten und zu implementieren.

Bei der Integration von Systemen, wie einer CRM-Plattform, stehen Lösungsarchitekten vor der Herausforderung, ein Gleichgewicht zwischen schneller Bereitstellung und langfristiger Skalierbarkeit zu finden. Einerseits besteht der Druck, funktionale Lösungen schnell bereitzustellen, um unmittelbare Geschäftsanforderungen zu erfüllen, beispielsweise dem Vertriebsteam den Zugriff auf wichtige Kundendaten in Echtzeit zu ermöglichen. Andererseits müssen diese Schnittstellen so entwickelt werden, dass sie zukünftiges Wachstum und Integration unterstützen, um den sich im Laufe der Zeit verändernden Anforderungen, zusätzlichen Systemen und größeren Datenmengen gerecht zu werden. Dieser Balanceakt wird durch konkurrierende Prioritäten weiter erschwert. Eine schnelle Bereitstellung bevorzugt oft leichtgewichtige und minimal komplexe Schnittstellen, die mit begrenzten Ressourcen schnell implementiert werden können. Diese Schnittstellen könnten jedoch die Robustheit oder Flexibilität vermissen lassen, die für eine nahtlose Integration in zukünftige Systeme oder die Bewältigung wachsender organisatorischer Anforderungen erforderlich ist. Im Gegensatz dazu erfordert die Entwicklung einer langfristigen Skalierbarkeit zusätzlichen Aufwand im Vorfeld, wie die Implementierung aggregierter oder wiederverwendbarer Datenschnittstellen. Dies kann die anfängliche Bereitstellung verzögern, verbessert jedoch die allgemeine Belastbarkeit und Anpassungsfähigkeit des Systems erheblich.

Durch die Einordnung von Schnittstellen innerhalb der DIQs erhalten Lösungsarchitekten eine strukturierte Methode zur Bewertung und Abstimmung ihrer Entscheidungen, um sowohl unmittelbare Projektziele als auch übergeordnete Unternehmensstrategien zu berücksichtigen. Leichtgewichtige Schnittstellen können beispielsweise die Bereitstellung beschleunigen und harte Deadlines einhalten. Sie müssen jedoch auch auf ihre Kompatibilität mit zukünftigen Integrationen geprüft werden, um kostspielige Redesigns zu vermeiden. Mithilfe der DIQs können Lösungsarchitekten erkennen, wo Kompromisse notwendig sind und wo sich Investitionen in Skalierbarkeit auszahlen. So wird sichergestellt, dass kurzfristige Erfolge den langfristigen Erfolg nicht gefährden.

## Zusammenarbeit durch DIQs: Überbrückung von Rollen

Die DIQs fördern die Zusammenarbeit zwischen Unternehmens- und Lösungsarchitekten, indem sie eine gemeinsame Sprache bieten, die verschiedene Perspektiven vereint. Dadurch unterstützen sie die Entwicklung einer kohärenten Datenstrategie, die über die einzelnen Rollen hinausgeht.

In Workshops oder Planungsmeetings, die auf den DIQs basieren, können Prioritäten für Schnittstellen abgestimmt werden, um sicherzustellen, dass taktische Entscheidungen zu langfristigen Zielen beitragen. Diese Zusammenarbeit verbessert nicht nur das Schnittstellendesign, sondern schafft auch Vertrauen und Synergien zwischen den Teams. Die DIQs sind zudem hilfreich, wenn Schnittstellenanforderungen mit Entwicklungsteams geteilt werden, da sie ein gemeinsames Verständnis des erwarteten Ergebnisses gewährleisten. Besonders nützlich sind sie, wenn konkrete Richtlinien und Best Practices für jeden Quadranten bereitgestellt werden.

## Fazit

Das Data Interface Quadrants Framework (DIQs) ist mehr als nur ein Werkzeug – es dient als strategischer Begleiter. Durch die visuelle Darstellung kritischer Dimensionen von Datenschnittstellen ermöglichen die DIQs Architekten und Unternehmen, technische Entscheidungen mit den Geschäftszielen in Einklang zu bringen und Investitionen zu priorisieren, die den Wert steigern. Unternehmensarchitekten erhalten eine zusätzliche strategische Perspektive für die langfristige Planung, während Lösungsarchitekten die DIQs nutzen können, um sicherzustellen, dass der Projekterfolg mit den übergeordneten Zielen übereinstimmt und die Entwicklungsteams genau wissen, was von ihnen erwartet wird.

Vor allem haben wir die DIQs entwickelt, um die Zusammenarbeit zu fördern und die Kluft zwischen Strategie und Ausführung zu überbrücken. Sie bieten einen gemeinsamen Rahmen, der Architekten hilft, die Komplexität zu meistern, Innovationen voranzutreiben und robuste Datenökosysteme zu schaffen. Angesichts der Herausforderungen bei Integration, Skalierbarkeit und Governance sind die DIQs eine wertvolle Ressource für Klarheit, Orientierung und Kommunikation.

Setzt die DIQs in eurer Organisation, eurem Team oder eurem Projekt ein. Nutzt sie, um Datenstrategien zu analysieren, zu optimieren und zu verbessern. Teilt anschließend eure Gedanken und Erfahrungen mit uns, damit wir die DIQs weiterentwickeln und sie in unserer schnelllebigen, datengesteuerten Welt noch nützlicher machen können. Wir freuen uns auf eure Geschichten!

Kategorisierung von Schnittstellen: Data Interface Quadrants (DIQs)

*Viele Unternehmen setzen große Hoffnungen in API-Plattformen. Sie sollen Integrationen erleichtern, Wiederverwendung fördern und das Unternehmen technologisch zukunftssicher machen. Nach der Einführung scheint vieles auf einem guten Weg zu sein: Die Plattform ist etabliert, erste Projekte wurden erfolgreich umgesetzt und das Team rund um die API-Plattform baut Wissen auf. Doch nach einer gewissen Zeit zeigt sich ein wiederkehrendes Muster. Die Nachfrage nach neuen APIs nimmt ab, bestehende APIs werden kaum wiederverwendet und das API-Team wird zunehmend als Flaschenhals wahrgenommen. APIs entstehen meist erst dann, wenn sie unmittelbar für ein Projekt benötigt werden – oft unter Zeitdruck und ohne Blick auf eine langfristige Strategie.*

In diesem Blog Post verwenden wir die Begriffe *Integration* und *API* und definieren sie dafür wie folgt:

> **Integration**: bezeichnet die Verknüpfung verschiedener Systeme oder Anwendungen, um einen nahtlosen Datenaustausch zu automatisierte Prozesse zu ermöglichen.

>**API**:  ist eine definierte Schnittstelle, die es Anwendungen ermöglicht, miteinander zu kommunizieren.

Das API-Team ist sich dieser Herausforderungen bewusst und versucht gegenzusteuern. Es werden Workshops organisiert, Best Practices definiert und Optimierungen der Plattform, wie z.B. die Entwicklung von Self-Service Funktionalitäten, angestoßen. Doch strukturelle Probleme lassen sich auf diese Weise nur schwer lösen. Solange Integrationen in einzelnen Projekten isoliert betrachtet werden und keine übergreifende API-Strategie existiert, bleibt die Plattform in ihrer Wirkung begrenzt. APIs entstehen und verschwinden, ohne dass sie langfristig einen Mehrwert bieten.

## Warum die Bereitstellung von APIs nicht automatisch zu ihrer effektiven Nutzung führt
Was viele Organisationen unterschätzen: Der Aufbau einer API-Plattform ist nur der erste Schritt. Der eigentliche Mehrwert entsteht erst dann, wenn APIs nicht nur bereitgestellt, sondern auch aktiv genutzt und weiterentwickelt werden. Doch genau hier scheitern viele Organisationen. Die Gründe sind vielfältig: Oft fehlt eine übergeordnete API-Strategie, die eine konsistente und wiederverwendbare API-Landschaft fördert, andere Organisationen scheitern dagegen an der Umsetzung oder Kommunikation der Strategie.

Ein zentrales Problem ist, dass APIs oft als rein technische Notwendigkeit verstanden werden, nicht als Business-Enabler. Solange sie nur entwickelt werden, weil eine Schnittstelle auf die Schnelle gebraucht wird, fehlt die strategische Komponente. APIs entstehen sehr oft ausschließlich reaktiv im Rahmen eines bestimmten Projekts – als Mittel, um eine Integration schnell zum Laufen zu bringen. Dabei wird wenig darüber nachgedacht, ob eine API auch für andere Anwendungsfälle geeignet und damit wiederverwendbar sein könnte, sie langfristig erweiterbar ist oder einen nachhaltigen Mehrwert für das Unternehmen schafft.

Diese projektgetriebene Entwicklung führt dazu, dass APIs kaum über den unmittelbaren Anwendungsfall hinaus gedacht werden. Das Ergebnis ist eine Sammlung von punktuellen Integrationen zwischen genau zwei Systemen. Diese Integrationen erfüllen kurzfristig ihren Zweck, führen aber langfristig zu einer fragmentierten, schwer wartbaren Architektur.

Auch ist die Rolle des API-Teams ein Problem. Häufig wird es als reiner „Service Provider“ betrachtet, der Integrationen auf Zuruf entwickelt. Die Einbindung erfolgt oft erst spät im Projekt, wenn die grundlegenden Anforderungen bereits festgelegt sind und keine Möglichkeit mehr besteht, das API-Design hinsichtlich Wiederverwendung zu optimieren. Dadurch bleibt das API-Team auf die Umsetzung beschränkt und kann keinen strategischen Einfluss auf die API-Landschaft nehmen. Gleichzeitig fehlt es vielen Entwicklungsteams an einem tiefgehenden Verständnis für gutes API-Design, weil es keine systematische Unterstützung oder Enablement-Prozesse gibt.

Ein weiteres Problem ist die Wahrnehmung der Plattform selbst. Anstatt als Enabler für moderne Integration gesehen zu werden, wirkt sie auf viele Entwickler eher wie eine Vorgabe, die es zu erfüllen gilt. Die Technologie steht im Mittelpunkt, nicht der eigentliche Mehrwert von APIs. Statt die Plattform zu nutzen, um Integrationen nachhaltig zu verbessern, wird sie oft nur als Mittel zum Zweck zur punktuellen Integration eingesetzt. Das führt dazu, dass APIs entstehen, weil sie ad hoc gebraucht werden – nicht, weil sie als wertvolles Werkzeug zur Optimierung von Geschäftsprozessen verstanden werden.

Gleichzeitig sind API-Plattformen oft komplex und schwerfällig. Ohne größere Anpassungen werden nur wenige Standardfälle für Integrationen abgedeckt und der Automatisierungsgrad ist niedrig. Damit wirken sie auf Entwicklungsteams oft abschreckend und nicht gewinnbringend.

Auch API-Governance wird oft falsch verstanden. Zwar existieren in vielen Unternehmen technische Standards, doch es fehlen Metriken, um den tatsächlichen Nutzen und die Effektivität von APIs zu bewerten. Fragen wie „Wird eine API tatsächlich genutzt?“, „Wie lange dauert es, bis Entwicklungsteams sie erfolgreich einsetzen können?“ oder „Trägt die API in Zukunft dazu bei, Integrationsaufwände zu reduzieren?“ werden selten gestellt. Ohne diese Daten bleibt unklar, ob eine API wirklich einen Mehrwert liefert oder nur eine weitere technische Schnittstelle ist, die in Vergessenheit gerät.

Letztlich reicht es nicht aus, APIs einfach nur bereitzustellen. Sie müssen so gestaltet werden, dass sie langfristig Wert stiften, effizient nutzbar sind und strategisch zur Unternehmensarchitektur passen. Fehlt dieser Ansatz, bleibt eine API-Plattform ein gut gemeintes, aber wirkungsloses Werkzeug, das eher als Hürde denn als Enabler wahrgenommen wird.

## API-Effektivität durch Team Topologies
Der Schlüssel zu effektiven APIs liegt nicht nur in der Technologie, sondern vor allem in der richtigen Organisationsstruktur. Unternehmen müssen den Wechsel von einer projektgetriebenen API-Entwicklung zu strategischen API-Produkten vollziehen. Hier bietet das Konzept der **Team Topologies** einen klaren Rahmen.

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/YcV9FmkrQOyVUqMeOZpn" width="400" height="500"/>

*Image taken from the book Team Topologies by Matthew Skelton and Manuel Pais, 2019. Used with permission.*

Team Topologies definiert vier verschiedene Team-Typen, von denen drei im API-Kontext besondere Relevanz haben: Platform Team, Enabling Team und Stream-Aligned Teams.

Ein **Platform Team** bildet das Rückgrat der API-Plattform. Es stellt nicht nur die Infrastruktur bereit, sondern sorgt auch für eine gute Developer Experience, fördert die Wiederverwendbarkeit von APIs und bietet Self-Service-Funktionen mit hohem Automatisierungsgrad an. Anstatt sich auf Governance oder Tooling zu beschränken, sollte das Platform Team APIs gezielt nutzbar machen und eine API-Strategie mit messbaren Zielen entwickeln.

Ein **Enabling Team** unterstützt andere Teams dabei, APIs als Produkte zu denken. Es hilft Entwicklungsteams, Best Practices zu etablieren, Wiederverwendung zu fördern und APIs gezielt für eine breitere Nutzerbasis zu gestalten. Ohne eine solche Unterstützung bleibt API-Entwicklung oft isoliert und ineffektiv.

Die größte Veränderung entsteht jedoch in den **Stream-Aligned Teams**. Diese Teams verantworten ihre APIs eigenständig und entwickeln sie mit einem langfristigen Produktgedanken. APIs werden nicht mehr nur gebaut, um ein Projekt abzuschließen, sondern um nachhaltig Mehrwert zu schaffen. So entsteht echte API-Ownership, die sich direkt auf die Effektivität auswirkt. Wenn Teams die volle Verantwortung für ihre APIs übernehmen, denken sie über deren langfristige Nutzung, Erweiterbarkeit und Qualität nach. Dadurch entstehen besser durchdachte, wiederverwendbare und wirtschaftlich sinnvolle APIs.

Ein zentraler Vorteil, der durch Team Topologies realisiert wird, ist die Abkehr von isolierten Punkt-zu-Punkt-Integrationen hin zu strategisch geplanten API-Produkten. APIs müssen langfristig gedacht werden, mit einer klaren Roadmap und definierten Metriken zur Erfolgsmessung: Adoption Rate, Time-to-First-Success oder die Reusability Rate sind essentiell, um zu verstehen, ob eine API tatsächlich genutzt und wiederverwendet wird oder nur ein weiteres technisches Artefakt bleibt.

## Fazit: API-Strategie entscheidet über den Erfolg
Eine API-Plattform allein reicht nicht aus, um nachhaltige Integrationserfolge zu erzielen. Entscheidend ist, dass APIs nicht nur bereitgestellt, sondern effektiv genutzt und weiterentwickelt werden. Ohne eine klar formulierte und umgesetzte Strategie bleibt eine API-Plattform eine technische Notwendigkeit, die genutzt wird, weil sie vorgeschrieben ist – mit der richtigen Teamstruktur wird sie hingegen zu einem echten Enabler für digitale Transformation.
Der Wechsel von reiner API-Bereitstellung zu API-Effektivität erfordert mehr als gute Technologie. Es geht darum, APIs als wertvolle Assets zu betrachten und ihre Entwicklung so zu organisieren, dass sie langfristig einen echten Beitrag zur Unternehmensstrategie leisten. Wer möchte, dass eine API-Plattform in der Organisation ihre erhoffte Wirkung entfaltet, muss über Technologie hinausdenken – und das Zusammenspiel von Teams, Prozessen und Strategie in den Mittelpunkt stellen.






Wenn die erhoffte Wirkung der API-Plattform ausbleibt

3 Steps to Access AWS Resources with Google Sign-In

How to create an AWS Lambda Authorizer for an Amazon API Gateway

*An Enabling Team is one of the four team types of the Team Topologies framework, as introduced by Matthew Skelton and Manuel Pais. How can this pattern be successfully applied to the design and development of APIs to create interfaces that really contribute to the business strategy?*

APIs are an important building block for digitalization and thus, the pressure on development teams to provide APIs is constantly growing. However, development teams often lack the necessary knowledge and experience, especially when they are mainly working in the ERP environment or in backend systems. Combined with pressing deadlines, this leads to APIs that are non-reusable, difficult to maintain, insecure and poorly documented. This frustrates and significantly slows down the development teams that rely on APIs and therefore has a negative impact on an organisation's ability to innovate. An API Enabling Team made up of experts can help teams to get started to ensure that high-quality APIs are created which contribute to the business strategy and promote the success of the organisation. This article highlights the challenges, foundations, prerequisites and opportunities of API enabling as an important success factor for establishing APIs as building blocks for digitalization.

## Challenges
Why do many development teams struggle to build high-quality APIs? Development teams that mainly work with legacy systems or have very specialised skills lack the necessary knowledge. Many practices of modern software development have not yet reached them, but these are essential for the development of high-quality APIs. 

In huge organisations, a large number of teams and different services have to be involved for the provisioning of interfaces. This includes teams who are responsible for integration, middleware (such as API management) or authorisation. This is particularly difficult to navigate for beginners, but it also puts experienced development teams to the test. 

In addition, requirements are often ‘thrown over the wall’ to the development teams. As a result, they have very little knowledge of the stakeholders of their APIs and therefore cannot identify with them or understand what they need to deliver to satisfy their stakeholders. The users of the API are thus not perceived as customers, but as someone who creates additional work for the team, namely the development of an API, which is not one of the team's core tasks and poses major challenges.

## Team Topologies as Foundation
The Team Topologies framework provides the basis for efficient software development. It distinguishes between four different types of teams: Stream-Aligned (business-oriented), Enabling (supporting), Complicated Subsystem (specialised) and Platform (accelerating). The teams interact using three different interaction patterns, either collaboratively, as-a-service or through facilitation. Exemplary interaction between the team types of the Team Topologies framework: 

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/Pug7EuqDTdaSn5j1CHUQ" width="700" alt="Exemplary interaction between the team types of the Team Topologies framework" />

*Image taken from the book Team Topologies by Matthew Skelton and Manuel Pais, 2019. Used with permission.*

An Enabling Team consists of experts who impart knowledge and expand the skillset of the stream-aligned teams by taking over the evaluation and testing of new tools, methods, frameworks and the like. They only support stream-aligned teams for a certain period of time and not permanently.

This article sheds light on the extent to which an Enabling Team specialised on APIs (hereinafter referred to as an API Enabling Team) can support Stream-Aligned Teams in broadening their skillset to make them fit for API design and implementation.

## Tasks of an Enabling Team for APIs
The primary task of an API Enabling Team is to support other teams and train them with regard to APIs. To do this, the team must develop a workshop concept that takes into account both modern standards as well as the organisation’s circumstances and API strategy. At best, the team supports the Stream-Aligned Teams during the design and development of their first API. It is important that the Enabling Team only provides support and does not develop the API itself. As the API Enabling Team cannot be familiar with every backend technology in the organisation, the Stream-Aligned Teams must be sufficiently familiar with their technology. Once the Enabling Team has provided support, it provides documentation that enables the Stream-Aligned Teams to go through the same process independently the next time. Of course, it will also remain available in the future for special questions, reviews and the like.

An API Enabling Team is most effective when it is also involved in high-level topics and can influence the API strategy, governance and operations so that the experiences with the individual teams can be taken into account and, ideally, incorporated there.

An API Enabling Team also helps to build a vibrant API community, as it establishes the necessary contacts with the individual development teams and can thus connect them with each other.

## Following a Philosophy
To be successful as an API Enabling Team, the team must be guided by the organisation's enterprise architecture and API strategy and derive its philosophy from these.

Based on the organisation's enterprise architecture, the API Enabling Team derives a golden path and identifies the procedures and tools that must be observed and used by the Stream-Aligned Teams. These can be, for example, certain architecture patterns, a prescribed API management tool or prescribed quality features.

Based on the organisation's API strategy, the Enabling Team supplements its philosophy with specific API topics. The main focus here is on aspects such as reusability, APIs as a product, user-centred development and API design first vs. code first.

It is important that the API Enabling Team makes its philosophy transparent and bases all its actions and workshops on it.

## Developing a workshop concept based on the philosophy
Based on its philosophy derived from the organisation, the API Enabling Team then develops a tailor-made workshop concept:

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/fECA7aLLR3qUjlmNosuU" width="500" alt="How to derive a workshop concept" />

The workshop concept consists of individual building blocks and must take into account the different levels of knowledge of different Stream-Aligned Teams. The following topics should at least be covered by the workshop concept: 
* Basic functionality of an API
* User-centred API development and stakeholder involvement, including developer experience
* Various interaction patterns and their areas of application
* Creation of a data model
* API design & standard formats (e.g. OpenAPI)
* API guidelines, standards and helpful tools in the organisation and beyond
* API management in connection with the topics of security and authentication/authorisation
* Backend development (as far as possible)
* Testing

The development of such a comprehensive workshop concept requires time and expertise. Further development and improvement of the concept based on experience with the Stream-Aligned Teams is essential.

## Implementing the workshop concept
To test the workshop concept, the API Enabling Team first approaches selected Stream-Aligned Teams that are open to new ideas and direct dialogue. After trialling, all Stream-Aligned Teams are given the opportunity to make use of the API Enabling Team to develop their first high-quality API. Firstly, the API Enabling Team always clarifies the requirements and expectations with the respective Stream-Aligned Team and makes its philosophy transparent. It must then clarify that APIs are the right technical solution for the tasks of the Stream-Aligned Team. It often turns out that this is not the case at all. However, if this is the case, the necessary workshops and work sessions can then be planned together in the way that best suits the Stream-Aligned Team's day-to-day work. Once the workshops have been held, the Enabling Team systematically collects feedback and integrates the Stream-Aligned Team into an API community, where team members can share problems, challenges and successes with other development teams. 
It is important that no Stream-Aligned team is forced into enabling if it does not want to. However, experience shows that good enabling is spread by word of mouth among teams. This automatically increases the demand for enabling.

## Platform Aspects
In order to work effectively and efficiently as an API Enabling Team, the general process of how APIs are created in the organisation must be as lean and clear as possible. The team must be enabled to improve the process together with other teams. It is also a good idea to establish an API Platform Team if many parts of the existing process are not yet automated. Automated API operations support the Enabling Team in transferring knowledge more quickly and making the existing services known to the Stream-Aligned Teams rather than reinventing the wheel for each individual Stream-Aligned Team. At the same time, the offered services help to reduce the cognitive load for the Stream-Aligned Teams, who already have to learn a lot of new things during the enabling process.

## Prerequisites for success
In order for the introduction of an API Enabling Team to be successful, a number of prerequisites must be met. Firstly, it is important that the team has the support of management. As the Enabling Team itself does not write any software and therefore does not deliver any demonstrable products, management must be convinced of its importance and also use the right metrics for evaluation. The number of APIs created, for example, which is often used as a metric, is only meaningful to a limited extent, as it neither says anything about the quality of the APIs nor takes into account teams for which an API was not a sensible solution.

A successful API Enabling Team also works with many other teams, mainly Platform, Complicated Subsystem and other Enabling Teams (e.g. authorisation teams, integration teams, etc.). These teams must be prepared to exchange the necessary information with the API Enabling Team which they share with the Stream-Aligned Teams in a condensed and processed form.

Another important prerequisite for the success of an API Enabling Team is to motivate the Stream-Aligned Teams to collaborate with them. This is difficult to achieve if the costs for the Enabling Team are passed on internally to the Stream-Aligned Teams. The enabling should be free of charge for all teams and it should be as simple as possible to make use of it.

## Conclusion
An API Enabling Team, based on the team types introduced in Team Topologies, successfully supports Stream-Aligned Teams in publishing their first API following a well-established approach. An organisation that relies on an API Enabling Team can ensure that high-quality APIs are created, which contribute to the business strategy and success of the organisation. The Enabling Team achieves this through a customised workshop concept, which ensures that Stream-Aligned Teams learn and master all important tasks related to the creation, development and publication of APIs.

The success of an API Enabling Team is closely linked to the support of management, the willingness of other central teams to work together and the motivation of the Stream-Aligned Teams. It is only when these requirements are met that the API Enabling Team can become a critical factor in the success of your business.

Charge your APIs Volume 29: API enabling as a factor for success

In today’s rapidly evolving, data-driven world, organisations face an increasingly complex challenge: how to design, implement, and manage data interfaces that meet both immediate operational demands and long-term strategic business objectives. A data interface is a defined connection point where data is exchanged between systems, applications, or components. It specifies the rules, formats, and protocols needed for smooth communication and interoperability, acting as the backbone of modern data ecosystems.

Organisations became aware of data being central to decision-making, driving innovation, and leading to competitive advantage. However, clarity in navigating the myriad possibilities of data interface design is often elusive, particularly for software architects who must bridge the divide between technical solutions and business outcomes.

This is where the Data Interface Quadrants (DIQs) framework steps in as a transformative tool. The DIQs provide a structured, visual approach to understanding and categorising data interfaces, empowering architects, development teams, and decision-makers to navigate complexity with confidence. By distilling the complexities of data interfaces into an intuitive format, DIQs offer insights that drive better strategic alignment and informed decision-making.

In this blog post, we unpack the potential of the DIQs and explore their value through two key lenses: the enterprise architect, who focuses on long-term organisational strategy, and the solution architect, who addresses project-specific implementation challenges. Together, these perspectives reveal how DIQs enable them to collaborate effectively to create and modernise robust, future-proof data ecosystems. The DIQs are more than just a diagram - they are a compass for navigating the trade-offs inherent in data interface design.

## Introducing the DIQs

![data-interface-quadrants-plain.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/ojiHNTPMR7uzJZM3aCte)

The DIQs offer a structured way to categorise data interfaces along two primary dimensions: the extent of data processing and the scope of its consumers. The horizontal axis of the DIQs focuses on the degree of data aggregation or transformation. On the left side, it emphasises raw data, where minimal or no transformation is applied, catering to use cases that require base-level data in its original form. On the right side, the framework highlights aggregated or transformed data, which is designed to support specific use cases or provide enhanced service-level functionality.

The complexity of data processing increases as you move from raw data to aggregated or transformed data. Raw data requires minimal intervention and is typically faster to provide but may demand more effort from consumers to extract meaningful insights. On the other hand, aggregated or transformed data involves additional processing steps, such as combining datasets, applying business logic, or reformatting data to fit specific use cases. While this adds a layer of complexity to the creation and maintenance of the interface, it can significantly reduce the effort required by consumers, making the data more immediately usable for their needs.

The vertical axis in the DIQs addresses the scope of consumers who interact with the data. At the bottom, the focus is on product-internal or usecase specific interfaces. These are typically consumed by a single team or a well-defined, technical audience with shared expertise. Conversely, the top of the DIQs shifts attention to external and reusable interfaces, which are designed to accommodate multiple teams and diverse audiences. These can include individuals with varying technical skills or even unknown consumers.

The framework defines four quadrants, each representing a specific type of data interface. The **Data Link** quadrant, located at the bottom-left, represents raw data interfaces used within a single product or team. These interfaces are simple and direct, often involving minimal transformation and primarily serving technical audiences with clear, shared requirements. The **Backend for Fronted (BFF)** quadrant, positioned at the bottom-right, includes usecase specific interfaces that offer aggregated or transformed data. These interfaces are tailored for particular application needs and are optimised for efficiency within a single product or team context. Development teams usually design and implement both types of interfaces with a strong focus on the technology.

At the top-left, the **Platform Data Product** quadrant represents raw data interfaces that are external and reusable. These interfaces provide foundational data in its original form to a broad audience, including unknown consumers or those with varying technical backgrounds. They prioritise reusability and scalability over specificity. Finally, the **Composition Service** quadrant at the top-right captures external and reusable interfaces offering aggregated and transformed data. These interfaces are designed to meet diverse use cases and are consumed by multiple teams, making them the most complex to build and maintain but the most versatile in addressing organisational needs. 
The broader audience requires development teams to design and implement both types of interfaces with a strong focus on the business requirements instead of technology.

## The Implications of an API-First Business Model

As organisations strive to become API-First, APIs become the relevant business model for them. Therefore, the focus for data interfaces shifts more towards the top quadrants of the DIQs. Instead of building product internal and usecase specific interfaces, development teams have to focus on building more external and reusable interfaces for larger audiences which also results in a higher business impact. However, if the team’s experience so far lies in technology building **Backend for Frontend** interfaces, they might not be aware of what’s needed to build a successful **Composition Service** aiming for business impact. Enabling and platform teams can empower development teams supporting the shift from APIs as solely technical interfaces to business relevant products. The DIQs can help visualise such strategic decisions and their implications on data interface design.

![data-interface-quadrants-api-first.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/YzoIBqRdT2z3FPXec4Dm)

## Enterprise Architects: The DIQs as Strategic Lens

Enterprise architects operate at the intersection of business strategy and technological implementation, thereby also shaping the overarching data architecture. The DIQs equip them with a holistic perspective, enabling strategic oversight that bridges the gap between organisational objectives and technical realities.

Using the DIQs, enterprise architects can categorise and evaluate interfaces, prioritising investments where they matter most. For instance, interfaces that are product internal and usecase specific, offering aggregated or transformed data, can enhance scalability, while those designed for external and reusable purposes, providing raw data, present opportunities for optimisation as they require minimal data processing but have a high impact on the business due to a broad audience. The DIQs also help identify bottlenecks and redundant systems, guiding efforts to streamline processes and enhance integration.

Moreover, the DIQs serve as a communication tool by presenting data interfaces in a clear, visual format. Enterprise architects can use it to facilitate discussions with stakeholders to align technical initiatives with broader business goals. For example, in a digital transformation project, the DIQs help to spotlight interfaces that require redesign or investment, ensuring decisions made today support future growth. In addition, enterprise architects can identify development teams needing more support from enabling and platform teams to make sure that redesign and investment are successful.

## Solution Architects: Bridging Strategy and Execution

Solution architects bring ideas to life by designing systems that meet immediate project demands while adhering to broader architectural principles. The DIQs help them navigate competing priorities, offering a structured lens to evaluate and implement data interfaces effectively.

When integrating systems, for example a CRM platform, solution architects face the challenge of balancing rapid delivery with long-term scalability. On one hand, there is pressure to deliver functional solutions quickly to meet immediate business needs, such as enabling a sales team to access critical customer data in real time. On the other hand, these interfaces must also be designed with future growth and integration in mind, ensuring they support evolving requirements, additional systems, and increased data volumes over time. This balancing act is further complicated by competing priorities. Rapid delivery often favors lightweight and minimally complex interfaces that can be implemented quickly with limited resources. However, these interfaces may lack the robustness or flexibility required to integrate seamlessly with future systems or handle growing organisational demands. Conversely, designing for long-term scalability might require additional time and effort upfront, such as implementing aggregated or reusable data interfaces, which can delay initial delivery but significantly enhance the system’s overall resilience and adaptability. 

By mapping options within the DIQs, solution architects gain a structured way to evaluate and align their decisions with both immediate project goals and overarching enterprise strategies. For example, lightweight interfaces may expedite delivery, meeting urgent deadlines, but must also be assessed for compatibility with future integrations to avoid costly redesigns. Using the DIQs, they can identify where compromises are necessary and where investments in scalability will pay off, ensuring that short-term achievements do not undermine long-term success. 

## Collaboration Through DIQs: Bridging Roles

The DIQs transcend individual roles, fostering collaboration between enterprise and solution architects. The quadrants serve as a ubiquitous language, bridging these perspectives to create a cohesive data strategy.

Workshops or planning sessions anchored in the DIQs can align priorities, ensuring tactical decisions contribute to long-term goals. This iterative collaboration not only enhances interface design but also builds trust and synergies between teams. In addition, the DIQs can be a useful tool to communicate interface requirements to development teams and make sure everyone involved has the same understanding of the expected outcome. Especially, if concrete guidelines and best practices for each quadrant are provided.

## Conclusion

The Data Interface Quadrants framework (DIQs) is more than a tool - it can serve as a strategic enabler. By mapping critical dimensions of data interfaces into a visual structure, DIQs empower architects and organisations to align technical decisions with business objectives and prioritise investments that drive value. Enterprise architects gain an additional strategic lens for long-term planning, while solution architects use DIQs to ensure project success aligns with broader goals and development teams understand what’s expected from them.

Above all, we created the DIQs to foster collaboration, bridging the gap between strategy and execution. They provide a shared framework that enables architects to navigate complexity, drive innovation, and build resilient data ecosystems. As organisations face the challenges of integration, scalability, and governance, DIQs emerge as an essential resource for clarity, direction, and communication.

Explore the DIQs in your organisation, in your team, or in your project. Use them to analyse, optimise, and elevate your data strategies. Share your thoughts and experiences to help improve them and make the DIQs even more useful in our fast-changing, data-driven world. We’re excited to hear your stories!


Introducing Data Interface Quadrants (DIQs)

*Many companies have high hopes for API platforms, expecting them to facilitate integrations, promote reuse and future-proof the company technologically. Initially, a lot of things seem to go well: the platform is established, the first projects have been successfully implemented and the team around the API platform builds knowledge. However, over time, a recurring pattern emerges. The demand for new APIs declines, existing APIs are rarely reused, and the API team is increasingly perceived as a bottleneck. APIs are usually only created when needed for a project – often under time pressure and without a long-term strategy.*

In this blog post, we use the terms *integration* and *API* and define them as follows:

> **Integration**: refers to the linking of different systems or applications to enable seamless data exchange for automated processes.

> **API**: is a defined interface that allows applications to communicate with each other.

The API team recognises these challenges and actively works to counteract them. They organise workshops, define best practices and initiate platform optimisations, such as developing self-service functionalities. However, addressing structural problems proves difficult with these efforts alone. As long as integrations are handled in isolation within individual projects and there is no overarching API strategy, the platform’s effectiveness remains limited. APIs are created and discarded without delivering long-term value.

## Why simply providing APIs doesn't guarantee their effective utilisation
Many organisations underestimate that building an API platform is just the first step. The real added value only comes when APIs are not only provided, but also actively used and further developed. However, many organisations fail at this stage. The reasons are numerous: often, they lack an overarching API strategy that promotes a consistent and reusable API landscape.

A key problem is that many view APIs as merely a technical necessity rather than a business enabler. When developed solely to meet immediate interface needs, they lack a strategic component.  Often, APIs are created reactively within specific projects to quickly establish integrations.  This approach overlooks whether an API could serve other use cases and be reusable, whether it can be extended long-term, or whether it provides sustainable value for the company.

 This project-driven development leads to APIs being considered only for their immediate use case. Consequently, organisations end up with a collection of selective integrations between exactly two systems. While these integrations serve their short-term purpose, they eventually create a fragmented architecture that is difficult to maintain.

 The role of the API team poses a problem as well. Many view it purely as a "service provider" that develops integrations on demand. Often, the team gets involved late in the project, after the basic requirements have already been defined, leaving no opportunity to optimise the API design for reuse. Consequently, the API team focuses solely on implementation and cannot influence the API landscape strategically. Additionally, many development teams lack a thorough understanding of good API design due to the absence of systematic support or enablement processes.

 Another problem lies in the perception of the platform itself. Many developers view it as a requirement to be met rather than an enabler of modern integration. The focus remains on the technology rather than the actual added value of APIs. Instead of leveraging the platform to improve integrations long-term, developers often use it merely as a means for selective integration. Consequently, APIs are created out of immediate necessity rather than being recognized as valuable tools for optimising business processes.

At the same time, API platforms can be challenging and cumbersome to work with. They typically cover only a few standard integration cases and offer low levels of automation without significant customisation. This complexity frequently discourages development teams from utilising them.

Many also misunderstand API governance. While companies often have technical standards, they lack metrics to evaluate the actual benefits and effectiveness of APIs. They rarely ask questions like, "Is an API actually being used?", "How long does it take for development teams to successfully use it?", or "Will the API help reduce integration efforts in the future?". Without this data, determining whether an API truly delivers added value or is just another forgotten technical interface remains unclear.

Ultimately, simply providing APIs is not enough. They must be designed to deliver long-term value, be efficient to use, and align strategically with the enterprise architecture. Without this, an API platform becomes a well-intentioned but ineffective tool, perceived as a hurdle rather than an enabler.

## API Effectiveness through Team Topologies

Effective APIs depend not only on technology but also on the right organisational structure. Companies must transition from project-driven API development to strategic API products. The concept of **team topologies** offers a clear framework for achieving this.

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/YcV9FmkrQOyVUqMeOZpn" width="400" height="500"/>

*Image taken from the book Team Topologies by Matthew Skelton and Manuel Pais, 2019. Used with permission.*

Team Topologies defines four different team types, with three being particularly relevant in the API context: Platform Team, Enabling Team and Stream-Aligned Teams.

A **Platform Team** forms the backbone of the API platform. It provides the infrastructure, ensures a good developer experience, promotes API reusability, and offers self-service functions with a high degree of automation. Instead of limiting its role to governance or tooling, the platform team should focus on making APIs usable and developing an API strategy with measurable goals.

An **Enabling Team** helps other teams view APIs as products. It assists development teams in establishing best practices, promoting reuse, and designing APIs for a broader user base. Without this support, API development often remains isolated and ineffective.

The biggest change, however, occurs in **Stream-Aligned Teams**. These teams take ownership of their APIs and develop them with a long-term product perspective. They no longer build APIs just to complete a project but to create sustainable value. This approach establishes true API ownership, directly impacting effectiveness. When teams fully own their APIs, they consider long-term use, extensibility, and quality. This results in better-designed, reusable, and economically sensible APIs.

A key advantage of Team Topologies is the shift from isolated point-to-point integrations to strategically planned API products. Teams must build APIs with a long-term perspective, creating a clear roadmap and defining metrics to measure success. Adoption rate, time-to-first-success, and reuse rate are essential for understanding whether an API is actively used and reused or merely another technical artefact.

## Conclusion: API strategy is crucial for success

An API platform alone cannot achieve sustainable integration success. APIs must be effectively used and further developed, not just provided. A clearly formulated and implemented strategy is crucial; otherwise, the API platform remains a technical necessity used out of obligation. With the right team structure, however, it becomes a true enabler for digital transformation.

Achieving API effectiveness requires more than good technology; it involves viewing APIs as valuable assets and organising their development to ensure they contribute to corporate strategy over the long term. To maximise the benefits of an API platform in your organisation, focus beyond technology and emphasise the interaction between teams, processes, and strategy.


When your API platform lacks the desired impact

Lead API Consultant

Senior IT consultant

Key Account Manager

Senior Agile Coach & Consultant

<div><h2>1. Introduction</h2><div><div><p>Welcome Micronaut: a modern JVM-based full-stack framework. If you have not yet heard of Micronaut, then it is time to get informed and try it out. In this blog post you will get acquainted with Micronaut’s key features, scaffolding tools and a simple HTTP server and client example.</p></div><div><p>Here is a list of Micronaut’s key features:</p></div><div><p><strong>Supports Java, Groovy, and Kotlin.</strong> Being a JVM-based framework, Micronaut provides first-class support for Java, Groovy and Kotlin.</p></div><div><p><strong>Natively cloud-native.</strong> Micronaut’s cloud support is built right in, including support for common discovery services, distributed tracing tools, and cloud runtimes. Micronaut is ready to develop serverless applications and is designed for building resilient microservices.</p></div><div><p><strong>Fast startup time and low memory consumption.</strong> Micronaut avoids using reflection at runtime and uses compile-time AST transformations instead. This is why Micronaut has a fast startup time and a minimal memory footprint.</p></div><div><p><strong>Reactive and non-blocking.</strong> Micronaut is a non-blocking HTTP server built on Netty and has a declarative, reactive and compile-time HTTP client.</p></div><div><p><strong>Fast and easy testing.</strong> Efficient compile-time dependency injection and AOP.</p></div><div><p><strong>Fast data-access configuration.</strong> Micronaut provides sensible defaults that automatically configure your favourite data access toolkit and APIs to make it easy to write your own integrations.</p></div></div></div><div><h2>2. Prerequisites</h2><div><div><p>In order to run the examples in this article, you need to install the following tools:</p></div><div><ul><li><p><a href="http://sdkman.io/" target="_blank">SDKMAN</a>  – a tool for managing parallel versions of multiple SDKs</p><div><div>

```
curl -s "https://get.sdkman.io" | bash
```

</div></div></li><li><p>Java Development Kit</p><div><div>

```
sdk install java
```

</div></div></li><li><p>Micronaut CLI</p><div><div>

```
sdk install micronaut
```

</div></div></li></ul></div></div></div><div><h2>3. Scaffolding</h2><div><div><p>As many other modern frameworks, Micronaut comes with a handy CLI scaffolding tool. Micronaut CLI can be used as a CLI tool:</p></div><div><div><div>

```bash
mn help
mn help create-app
```

</div></div></div><div><p>It can also be used in interactive mode with command completion.</p></div><div><div><div>

```bash
$ mn
| Starting interactive mode...
| Enter a command name to run. Use TAB for completion:
mn> help
...
mn> help create-app
...
```

</div></div></div><div><p>Try both modes and see what you like more.</p></div><div><h3>3.1. Creating a new Gradle project</h3><div><p>Micronaut supports Java, Groovy, and Kotlin as first-class citizens. Let us create a new Java application using Micronaut CLI:</p></div><div><div><div>

```bash
mn create-app mn-hello-java
```

</div></div></div><div><p>This will scaffold a new Gradle project. If you prefer Maven, add a <code>--build maven</code> parameter. If you want to create a new Groovy or Kotlin project, add a <code>--lang</code> parameter:</p></div><div><div><div>

```bash
mn create-app --lang groovy mn-hello-groovy
mn create-app --lang kotlin mn-hello-kotlin
```

</div></div></div><div><p>By default Micronaut HTTP server will listen on a random port, but you can alter that by adding the following configuration to src/main/resources/application.yml:</p></div><div><div>src/main/resources/application.yml</div><div><div>

```yaml
micronaut:
    server:
        port: 8080
```

</div></div></div><div><p>The application can be immediately run with Gradle:</p></div><div><div><div>

```bash
cd mn-hello-java
./gradlew run
> Task :run
 
11:56:49.340 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 654ms. Server Running: http://localhost:8080
<=========----> 75% EXECUTING [7s]
```

</div></div></div><div><p>Now we can check that Micronaut is running:</p></div><div><div><div>

```bash
curl http://localhost:8080
{"_links":{"self":{"href":"/","templated":false}},"message":"Page Not Found"}
```

</div></div></div><div><p>To run the application with IntelliJ IDEA, you need to enable annotation processing:</p></div><div><ol><li><p>open Settings / Build, Execution, Deployment / Compiler / Annotation Processors</p></li><li><p>Set the checkbox “Enable annotation processing”</p></li></ol></div><div><p>Then you can run the application by executing the application class in IDEA.</p></div></div><div><h3>3.2. Adding an HTTP controller</h3><div><p>Let us use the CLI again to create an HTTP controller. Run this command in the directory of the project that we created:</p></div><div><div><div>

```bash
mn create-controller HelloController
| Rendered template Controller.java to destination src/main/java/mn/hello/java/HelloController.java
| Rendered template ControllerTest.java to destination src/test/java/mn/hello/java/HelloControllerTest.java
```

</div></div></div><div><p>As we can see, Micronaut cares about Test-Driven Development and has created a test along with the controller:</p></div><div><div>HelloController.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.HttpStatus;
 
@Controller("/hello")
public class HelloController {
 
    @Get("/")
    public HttpStatus index() {
        return HttpStatus.OK;
    }
}
```

</div></div></div><div><div>HelloControllerTest.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.context.ApplicationContext;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.client.RxHttpClient;
import io.micronaut.runtime.server.EmbeddedServer;
import org.junit.Test;
 
 
import static org.junit.Assert.assertEquals;
 
public class HelloControllerTest {
 
    @Test
    public void testIndex() throws Exception {
        EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class);
 
        RxHttpClient client = server.getApplicationContext().createBean(RxHttpClient.class, server.getURL());
 
        assertEquals(HttpStatus.OK, client.toBlocking().exchange("/hello").status());
        server.stop();
    }
}
```

</div></div></div></div><div><h3>3.3. Adding a compile-time-generated HTTP client</h3><div><p>Micronaut provides a great declarative compile-time HTTP client. You can use it for testing your own server (as we will do in the next example) or for communicating with external servers.</p></div><div><div><div>

```bash
mn create-client HelloClient
| Rendered template Client.java to destination src/main/java/mn/hello/java/HelloClient.java
```

</div></div></div><div><p>Here is what Micronaut creates:</p></div><div><div>HelloClient.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.http.client.Client;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.HttpStatus;
 
@Client("hello")
public interface HelloClient {
 
    @Get("/")
    HttpStatus index();
}
```

</div></div></div><div><p>That is all of it – only the interface. Micronaut will generate the implementation at compile time.</p></div></div></div></div><div><h2>4. Hello World</h2><div><div><p>Now that we got acquainted with Micronaut’s scaffolding CLI, let us create a more comprehensive example. We will extract the server API and reuse it in the HTTP controller in the production code and in the HTTP client in the test:</p></div>

![hello-micronaut-class-diagram.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/0Z4hyMFlRVidfbadfALv)

<p></p>Figure 2. Sharing server and client API</div></div><div><h3>4.1. Server API</h3><div><p>First, let us define the server API:</p></div><div><div>HelloApi.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.QueryValue;
 
public interface HelloApi {
 
    @Get("/")
    HelloMessage index(@QueryValue("name") String name);
}
```

</div></div></div><div><p>Here is what is happening:</p></div><div><ul><li><p>the annotation <code>@Get("/")</code> specifies the path and the HTTP method of the endpoint</p></li><li><p>the annotation <code>@QueryValue("name")</code> maps the GET parameter <code>name</code> to the method parameter <code>name</code></p></li><li><p>the return type <code>HelloMessage</code> tells Micronaut to serialize the POJO returned by the HTTP controller to JSON</p></li></ul></div><div><div>HelloMessage.java</div><div><div>

```java
package mn.hello.java;
 
public class HelloMessage {
    public String greeting;
}
```

</div></div></div></div><div><h3>4.2. HTTP controller</h3><div><p>Let us implement a simple HTTP controller that will return a greeting for the given name:</p></div><div><div>HelloController.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.http.annotation.Controller;
 
@Controller("/hello")
public class HelloController implements HelloApi {
 
    @Override
    public HelloMessage index(String name) {
        HelloMessage m = new HelloMessage();
        m.greeting = "Hello " + name + "!";
        return m;
    }
}
```

</div></div></div><div><p>Since we return a POJO in the controller, Micronaut considers the method blocking and will execute it on the I/O thread pool. However, it is also possible to write a non-blocking reactive implementation and return a non-blocking type such as <a href="http://reactivex.io/RxJava/javadoc/io/reactivex/Single.html"><code>Single</code></a> . In this case, the request is considered non-blocking and the method will be executed on the Netty event loop thread.</p></div></div><div><h3>4.3. HTTP client & testing</h3><div><p>Since we extracted the server API into a separate interface, we can now easily create an HTTP client for our application:</p></div><div><div>HelloClient.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.http.client.Client;
 
@Client("/hello")
public interface HelloClient extends HelloApi {}
```

</div></div></div><div><p>We don’t need to write any implementation, Micronaut will do that for us at compile time. Here is what a test can look like using this HTTP client:</p></div><div><div>HelloControllerTest.java</div><div><div>

```java
package mn.hello.java;
 
import io.micronaut.context.ApplicationContext;
import io.micronaut.runtime.server.EmbeddedServer;
import org.junit.Test;
 
import static org.junit.Assert.assertEquals;
 
public class HelloControllerTest {
 
    @Test
    public void testIndex() throws Exception {
        EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class);
 
        HelloClient client = server.getApplicationContext().getBean(HelloClient.class);
 
        HelloMessage serverResponse = client.index("codecentric");
 
        assertEquals("Hello codecentric!", serverResponse.greeting);
        server.stop();
    }
}
```

</div></div></div><div><p>In this test we actually spin up our Micronaut application and execute an HTTP request against it using the generated HTTP client.</p></div></div><div><h3>4.4. Docker-ready</h3><div><p>Micronaut CLI generates a Dockerfile as well, making it easy to package your application for a container environment such as Kubernetes. Let us run our example application with Docker:</p></div><div><ol><li><p>Build the application into a fat-jar:</p><div><div>

```
./gradlew build
```

</div></div></li><li><p>Build a Docker image:</p><div><div>

```
docker build . -t mn-hello-world
```

</div></div></li><li><p>Run the Docker image:</p><div><div>

```
docker run --rm -p 8080:8080 mn-hello-world
```

</div></div></li><li><p>Check that it is running:</p><div><div>

```
curl http://localhost:8080/hello?name=codecentric
{"greeting":"Hello codecentric!"}
```

</div></div></li></ol></div></div></div></div><div><h2>5. Conclusion</h2><div><div><p>In this article we have only scratched the surface of what Micronaut has to offer. Here is what’s left out of scope:</p></div><div><ul><li><p>Reactive programming</p></li><li><p>Database access with GORM</p></li><li><p>Service discovery</p></li><li><p>Serverless applications</p></li><li><p>Distributed tracing</p></li></ul></div><div><p>All in all, Micronaut is a fast-evolving framework and looks very promising. Go try it yourself or maybe even use it for your next project!</p></div></div></div><div><h2>6. Links</h2><div><div><ul><li><p>Micronaut home page: <a href="http://micronaut.io/">http://micronaut.io/</a> </p></li></ul></div></div></div>

Micronaut Microservices Framework: Introduction

IT Consultant & Developer

IT-Consultant

Head of Sales

Atlassian Solution Consultant

OpenAPI direkt in VS Code schreiben – geht das?

Renovate in Azure DevOps Pipelines with Presets and Custom Managers

Werkstudentin

Software Engineer

Frontend Developer

Senior Marketing Manager

Active Sourcerin und People Solutions Partnerin cc cloud GmbH

Vom simplen USB-Gerät zur Sicherheitslücke - BadUSB

IT-Security Consultant

<div><div><p>Mit Kotlin Multiplatform Mobile (KMM) steht ein weiteres Cross-Platform Framework in den Startlöchern. Diesmal geht JetBrains ins Rennen und versucht natürlich alles besser zu machen als alle anderen. Die Frage ist aber: Brauchen wir das wirklich? Ist es einfach nur eine weitere Kopie in neuem Gewand?<br /> Um das herauszufinden, habe ich eine kleine App gebaut und wir schauen uns gemeinsam an, wie das Ganze funktioniert. <a href="https://github.com/darthkali/kmmbikeshare" target="_blank">Hier findet ihr</a>  die Beispiel-App, auf die ich mich im Beitrag beziehe.</p><div><h2><strong>Grundlegender Aufbau von Kotlin Multiplatform Mobile</strong></h2><div><div><p>Starten wir zunächst mit dem Aufbau einer Kotlin Multiplatform Mobile-App. Ein KMM-Projekt basiert in erster Linie auf Modularisierung. Folgt man dem Standardweg von Kotlin, erhält man folgende Struktur:</p></div><div><div><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wZx4FYH6TZikCTxgemlf" alt="Bild zeigt wie die Struktur einer KMM App ist." /></div></div><div><p>Wir haben also ein Android-Modul, ein iOS-Modul und ein shared-Modul. In den Android- bzw. IOS-User-Interface-Modulen implementieren wir hauptsächlich Elemente für das User Interface, während wir die Business- und Datenlogik im shared-Modul umsetzen. Eine strikte Regel für die Abgrenzung gibt es jedoch nicht. Erscheint es für den Anwendungsfall sinnvoll, einen Teil der Businesslogik in die UI-Module zu ziehen, ist das mit Kotlin Multiplatform Mobile ohne Weiteres möglich. Die Implementierungen werden dann nicht zwischen den Systemen geteilt. Diese Flexibilität ist ein großer Vorteil von Kotlin Multiplatform Mobile.</p></div><div><p>Innerhalb des shared-Moduls erfolgt eine Aufteilung in common, iOS und Android Packages. Der größte Teil der Entwicklung findet im common Package statt. Hier liegt in der Regel die komplette Implementierung der Business- und Datenlogik. Also alles von der Implementierung der Datenbank, über die Remoteschnittstelle, bis hin zur Domänenlogik. In die beiden systemspezifischen Packages innerhalb des shared-Moduls kommen nur die Implementierungen, die wir für die jeweiligen Systeme separat entwickeln müssen. Das sind meist nur Treiberimplementierungen oder Ähnliches.</p></div><div><p>Neben den oben genannten Modulen gibt es dann auch das passende Pendant für die Tests. Auch hier erfolgt der Hauptteil im CommonTest Package während wir in den systemspezifischen Packages nur das Setup und die Treiber implementieren.</p></div><div><p>Damit wissen wir nun, wie der ganz grobe Aufbau der App ist. Wie das Ganze im Detail funktioniert, schauen wir uns in den kommenden Abschnitten an.</p></div></div></div><div><h2><strong>expect / actual – was ist das?</strong></h2><div><div><p>Bevor wir uns auf konkrete Implementierungen stürzen, müssen wir vorher noch eine wichtige Funktionalität betrachten. Ich habe im letzten Abschnitt erwähnt, dass wir für manche Anwendungsfälle separate Implementierungen benötigen. Wir brauchen also einen Mechanismus, der eine Weiche darstellt, um jeweils die spezifische Implementierung für die passende Plattform zu kompilieren.<br /> Hierzu kommt das Feature <em>expect / actual</em> zum Einsatz.</p></div><div><div>expect / actual</div><div>

```rouge highlight
// Common
expect fun sharedFunction(parameter: String): String


// iOS
actual fun sharedFunction(parameter: String): String {
    return “this is the iOS implementation”
}


// Android
actual fun sharedFunction(parameter: String): String {
    return “this is the Android implementation”
}
```

</div></div><div><p>Im common Package definieren wir, was implementiert werden soll, ohne jedoch eine direkte Implementierung an dieser Stelle zu erstellen. Das Keyword <em>expect</em> sorgt dafür, dass der Compiler eine Implementierung erwartet. Sie muss den gleichen Namen aufweisen und den gleichen Package-Pfad besitzen. Danach können wir die Methode oder Klasse in dem jeweiligen plattformspezifischen Package implementieren.</p></div></div></div><div><h2><strong>Codesharing zwischen iOS und Android</strong></h2><div><div><p>Kommen wir mal zu den harten Fakten. Was lässt sich denn jetzt wirklich alles teilen? Wie viel müssen wir ggf. doch parallel implementieren?</p></div><div><h3><strong>User Interface</strong></h3><div><p>Wie schon etwas weiter oben beschrieben sind wir absolut frei, was wir teilen wollen. Ob wir nur eine einzige Methode teilen oder die kompletten Daten und Domänenlogik ist uns komplett frei gestellt. Was wir jedoch nicht teilen sollten, ist das User Interface und seine Komponenten. Demzufolge müssen wir auch die UI-Tests jeweils plattformspezifisch entwickeln, was durchaus Sinn ergibt.</p></div></div><div><h3><strong>UI-State</strong></h3><div><p>Da der State in der Beispielanwendung lediglich eine Dataclass ist, kann man ihn durchaus teilen. Aber auch hier merkt man schon, dass wir für die jeweilige Plattform kleine Abweichungen einbauen müssen. Für iOS benötigen wir einen eigenen Konstruktor. So muss man es zwar dennoch doppelt schreiben, hat es aber zumindest in einer Datei, was sicherlich Geschmackssache ist.</p></div><div><div>UI-State</div><div>

```rouge highlight
data class BicycleSharingSystemListState(
    val isLoading: Boolean = false,
    val country: String = "",
    val bicycleSharingSystems: List<BicycleSharingSystem> = listOf(),
) {
    // Need secondary constructor to initialize with no args in SwiftUI
    constructor() : this(
        isLoading = false,
        country = "",
        bicycleSharingSystems = listOf(),
    )
}
```

</div></div></div><div><h3><strong>Remote-Zugriff</strong></h3><div><p>Für die Umsetzung der Remote-Schnittstelle haben wir Ktor als Framework verwendet, was auch JetBrains offiziell als Lösung vorgeschlägt.</p></div><div><p>Hierfür benötigen wir für iOS und Android zunächst eine separate Implementierung des Treibers. Es existieren also in der <em>commonMain</em> eine <em>KtorClientFactory</em>-Klasse, die wir als <em>expect</em> deklarieren, sowie jeweils eine <em>actual</em>-Klasse für Android und iOS. Deren Implementierungen sehen dann wie folgt aus:</p></div><div><div>KtorClientFactory</div><div>

```rouge highlight
expect class KtorClientFactory() {
    fun build(): HttpClient
}


iOS
actual class KtorClientFactory {
    actual fun build(): HttpClient {
        return HttpClient(Ios) {
            install(JsonFeature) {
                serializer = KotlinxSerializer(
                    kotlinx.serialization.json.Json {
                        ignoreUnknownKeys = true
                        useAlternativeNames = false

Android
actual class KtorClientFactory {
    actual fun build(): HttpClient {
        return HttpClient(Android) {
            install(JsonFeature) {
                serializer = KotlinxSerializer(
                    kotlinx.serialization.json.Json {
                        ignoreUnknownKeys = true
```

</div></div><div><p>Hier ist zu erkennen, dass die Implementierungen jeweils recht ähnlich sind. Der wichtigste Unterschied ist, dass bei der jeweiligen Plattform die passende Client-Engine (iOS respektive Android) an den <em>HttpClient</em> übergeben wird. Zur Serialisierung der Klassen nutzt KMM in beiden Fällen die KotlinX Serialization.</p></div><div><p>Mit der Implementierung der <em>KtorClientFactory</em> ist die Grundlage für die Remote-Anbindung bereits eingearbeitet. Das ist gleichzeitig die einzige Stelle, an der wir zwischen iOS und Android unterscheiden müssen. Die restliche Implementierung erfolgt wieder als komplett geteilte Codebasis.</p></div></div><div><h3><strong>Asynchronität</strong></h3><div><p>Neben vielen Klassen und Methoden, die problemlos zwischen iOS und Android teilbar sind, gibt es auch solche, bei denen das nicht ohne Weiteres machbar ist. Ein Beispiel ist die Verwendung von Coroutines. Um Asynchronität zu implementieren, bietet Kotlin für Android die <em>kotlinx.coroutines</em>-Bibliothek an. Das ist unter anderem für die Implementierung der Remote-Anbindung nötig. iOS kann diese Funktionalität jedoch nicht nutzen.</p></div><div><p>Zur Lösung dieses Problems gibt es verschiedene Ansätze:</p></div><div><h4><strong>KMP Beta</strong></h4><div><p>Zum einen kann man ganz entspannt einen Kaffee trinken und warten, bis KMM <a href="https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/" target="_blank">in die Beta kommt</a> . Hier wird laut JetBrains ein neuer Kotlin/Native-Memory-Manager zum Einsatz kommen. Damit sollen die Differenzen zwischen den beiden System begradigt werden und das Arbeiten mit Asynchronität deutlich vereinfacht werden.</p></div></div><div><h4><strong>FlowHelper</strong></h4><div><p>Wer nicht warten kann, hat auch jetzt schon Möglichkeiten. In unserer Beispiel-App haben wir das ganze mit einem Wrapper gelöst. Der FlowHelper kann unterscheiden, ob es eine iOS-App oder eine Android-App ist.</p></div><div><div>Flow Helper</div><div>

```rouge highlight
fun <T> Flow<T>.asCommonFlow(): CommonFlow<T> = CommonFlow(this)

class CommonFlow<T>(private val origin: Flow<T>) : Flow<T> by origin {
    fun collectCommon(
        coroutineScope: CoroutineScope? = null, // 'viewModelScope' on Android and 'nil' on iOS
        callback: (T) -> Unit, // callback on each emission
    ) {
        onEach {
            callback(it)
        }.launchIn(coroutineScope ?: CoroutineScope(Dispatchers.Main))
    }
}
```

</div></div><div><p>Für Android gibt man dem FlowHelper einfach den <em>Coroutinescope</em> mit und setzt den Callback auf <em>null</em>. Der Rest funktioniert dann wie gewohnt mit der <em>coroutinex.flow dependency</em>.</p></div><div><div>collectCommon Implementierung Android</div><div>

```rouge highlight
searchBicycleSharingSystems.execute(
    country = state.value.country,
).collectCommon(viewModelScope) { dataState ->
    state.value = state.value.copy(isLoading = dataState.isLoading)

    dataState.data?.let { bicycleSharingSystems ->
        appendBicycleSharingSystem(bicycleSharingSystems)
        saveAllBicycleSharingSystems(bicycleSharingSystems)
    }
}
```

</div></div><div><p>Bei iOS gibt man einen Callback mit. Man implementiert hier eine Funktion, die KMM dann anstelle der Couroutines ausführt.</p></div><div><div>collectCommon Implementierung iOS</div><div>

```rouge highlight
searchBicycleSharingSystems.execute(
    country: currentState.country
).collectCommon(
    coroutineScope: nil,
    callback: {
        >>> Here you can write your code
    })
```

</div></div></div></div><div><h3><strong>Datenbankzugriff</strong></h3><div><p>Für die Datenbankanbindung haben wir SQLDelight genommen. Das war zum Zeitpunkt der Erstellung das einzige Framework, das sowohl für Android wie auch für iOS eine Implementierung zur Verfügung stellte. Neben SQL Delight gibt es inzwischen auch die Möglichkeit, Realm als Datenbank zu nutzen.</p></div><div><h4><strong>Grundlegende Implementierung</strong></h4><div><p>Ähnlich der Remote-Schnittstelle mit Ktor bedarf es hier ebenfalls einer plattformspezifischen Implementierung der Treiber. Das haben wir ähnlich der Implementierung der PeopleInSpace App von John O’Reilly umgesetzt.</p></div><div><div>Platform Module für die Datenbank</div><div>

```rouge highlight
expect fun platformModule(): Module
```

</div></div><div><p>In den jeweiligen plattformspezifischen Modulen wird der passende Treiber genutzt und das Datenbankschema wie auch der Datenbankname übergeben.</p></div><div><div>Platform Module für die Datenbank – iOS</div><div>

```rouge highlight
actual fun platformModule() = module {
    single {
        val driver = NativeSqliteDriver(KmmBikeShareDatabase.Schema, "BikeShareDb.db")
        KmmBikeShareDatabaseWrapper(KmmBikeShareDatabase(driver))
    }
}
```

</div></div><div><div>Platform Module für die Datenbank – Android</div><div>

```rouge highlight
actual fun platformModule() = module {
    single {
        val driver =
            AndroidSqliteDriver(KmmBikeShareDatabase.Schema, get(), "BikeShareDb.db")
        KmmBikeShareDatabaseWrapper(KmmBikeShareDatabase(driver))
    }
}
```

</div></div><div><p>Das Datenbankschema wird zunächst in SQLDelight-Dateien definiert. Hier wird klassisch erst die Tabelle mit den Attributen und deren Eigenschaften definiert. Danach erfolgen die konkreten Datenbankabfragen (CRUD-Methoden), die später für die App zum Einsatz kommen. Innerhalb der <em>build.gradle.kts</em> wird die SQLDelight-Erweiterung definiert und sowohl der Datenbankname, als auch das Verzeichnis zu den oben beschriebenen Datenbankschemata hinterlegt. Um das anschließend nutzen zu können, müssen wir diesen Abschnitt zunächst kompilieren. Erfolgt eine Änderung an dem Schema, muss ein Rebuild erfolgen, damit die Änderungen wirksam werden.</p></div><div><p>SQLDelight erzeugt aus den Dateien einige neue Dateien, darunter die Implementierung der Datenbank, die die notwendigen Methoden und Verknüpfungen für die Entitäten und die Queries enthält. Außerdem sind hier weitere grundlegende Methoden inbegriffen, zum Beispiel <em>getLastInsertRowId</em>, die die zuletzt eingefügte ID zurückgibt. Das ist später sehr nützlich, um bei einem <em>Insert</em>-Befehl die ID zurückzugeben, um damit weiterzuarbeiten.</p></div><div><p>Die eigentliche Implementierung besteht aus dem Mapper, dem Datenbankmodell und den jeweiligen Repositories.</p></div></div></div><div><h3><strong>Test</strong></h3><div><p>Ein großer Vorteil der geteilten Codebasis ist, dass die Tests ebenfalls geteilt werden können.</p></div><div><p>In der App haben wir Tests für die lokalen Datenbankimplementierungen und für die Interactors erstellt. In diesem Abschnitt geht es also nur um die Tests, die sich innerhalb der geteilten Codebasis befinden.</p></div><div><p>Als Grundlage für die Tests haben wir den <em>BaseTest</em> eingebaut. Er ist im commonMain Package ebenfalls als <em>expect</em> deklariert, da es hier nötig ist, eine Unterscheidung zwischen Android und iOS zu treffen. Der <em>BaseTest</em> ist grundlegend so aufgebaut, dass es möglich ist, darin eine Suspend Function aufzurufen. Dazu muss er in einem <em>CoroutineScope</em> laufen. Außerdem müssen die Module für die Dependency Injection angelegt werden. Diese beiden Aufgaben sorgen dafür, dass die Basisklasse separat für Android und iOS gehandhabt werden muss. Eine weitere wichtige Aufgabe in Bezug auf Koin und den <em>CoroutineScope</em> ist es, diese zu starten und vor allem auch wieder zu stoppen.</p></div><div><div>BaseTest expect im Common Main</div><div>

```rouge highlight
expect abstract class BaseTest() : KoinTest {
    fun <T> runTest(block: suspend CoroutineScope.() -> T)
}
```

</div></div><div><h4><strong>Android</strong></h4><div><p>Unter Android gestaltet sich das unkompliziert. Hier können wir eine <em>KoinTestRule</em> erzeugen, die eine <em>ﬁnished</em>– und eine <em>starting</em>-Methode beinhaltet, die KMM dann automatisch ausführt. Der Coroutine Scope wird ebenfalls selbstständig gestartet und anschließend auch wieder beendet.</p></div><div><div>BaseTest unter Android</div><div>

```rouge highlight
@RunWith(AndroidJUnit4::class)
actual abstract class BaseTest : KoinTest {
    @get:Rule
    val koinTestRule = KoinTestRule.create {
        androidContext(ApplicationProvider.getApplicationContext())
        modules(
            network,
            ...
        )
    }
    actual fun <T> runTest(
        block: suspend CoroutineScope.() -> T
    ) { runBlocking { block(
}
```

</div></div></div><div><h4><strong>iOS</strong></h4><div><p>Für iOS müssen wir die gleiche Funktionalität erzeugen. Aktuell gib es hierfür noch keine spezielle Bibliothek, die das gewährleistet. Um die Funktionalität dennoch zu erzeugen, wurde eine Implementierung benutzt, die aus dem <em>touchlab/KaMPkit</em>-Repository stammt.</p></div><div><p>Für iOS wird der Dispatcher händisch in die <em>BaseTest</em>-Klasse eingebracht und erzeugt ebenfalls eine Methode, mit der die Tests ausführbar sind. Auch hier ist zu sehen, dass Koin zunächst gestartet wurde und später wieder beendet wird. Ebenfalls wird ein <em>CFRunLoop</em> gestartet, der eine Basisimplementierung unter iOS ist. Dieser wird zum Ende hin ebenfalls beendet.</p></div><div><div>BaseTest unter iOS</div><div>

```rouge highlight
actual abstract class BaseTest : KoinTest {

    @OptIn(DelicateCoroutinesApi::class)
    actual fun <T> runTest(block: suspend CoroutineScope.() -> T) {
        var error: Throwable? = null

        GlobalScope.launch(Dispatchers.Main) {
            try {
                initKoin()
                block()
            } catch (t: Throwable) {
                error = t
            } finally {
                stopKoin()
                CFRunLoopStop(CFRunLoopGetCurrent())
            }
        }
        CFRunLoopRun()
        error?.also { throw it }
    }
}
```

</div></div><div><p>Die Testklassen erben nun vom <em>BaseTest</em>. Innerhalb der Testklasse erzeugen wir zunächst eine Methode, die vor jedem Test läuft und einen Basissatz an Daten in der Datenbank implementiert. Sie ist mit <em>@BeforeTest</em> annotiert und nutzt die <em>runTest</em>-Methode aus dem <em>BaseTest</em>.</p></div><div><p>An den Tests wird nun noch die Annotation <em>@Test</em> notiert. Ebenso wird hier die <em>runTest</em>-Methode aus der <em>BaseTest</em>-Klasse wieder verwendet. Die Daten, die die <em>Setup</em>-Methode erzeugt, stehen anschließend vor jedem der Tests zur Verfügung. Die restliche Testimplementierung erfolgt wiederum nach dem Aufbau, wie er von der klassischen Android-Entwicklung bekannt ist.</p></div></div></div></div></div><div><h2><strong>Conclusion</strong></h2><div><div><p>Damit sind die wichtigsten Aspekte von Kotlin Multiplatform Mobile aufgezeigt. Wenn wir einmal auf die Ausgangsfrage zurückkommen, ob JetBrains nur eine weitere Kopie eines bestehenden Crossplatform Frameworks gebaut hat, kann man das ganz klar verneinen.<br /> KMM verfolgt einen deutlich anderen und vor allem freieren Weg, der auch jetzt schon viel Anklang in der Welt der Mobile-App-Entwicklung erhält.<br /> Es gibt bereits jetzt für alle wichtigen Teilbereiche, die in der App-Entwicklung nötig sind, einsatzbereite Frameworks. Wir können von der Businesslogik, über die Remoteanbindung bis zu den Tests alles teilen.</p></div><div><p>Dennoch gibt es auch Hürden, die man nehmen muss. Die Ersteinrichtung vor allem auf iOS-Seite ist mitunter schwierig. Auch sind die externen Bibliotheken mitunter noch nicht für KMM ausgelegt. Und auch die kleinen Schwierigkeiten mit dem Memory-Modell lassen noch Raum für Verbesserung.</p></div><div><p>Alles in allem sollte man dieses Framework nicht aus dem Blick verlieren. Für den entsprechenden Use Case kann und wird sich KMM durchaus relevant einsetzen lassen.</p></div></div></div></div></div>

Kotlin Multiplatform Mobile – Ein praktischer Einstieg

Vor drei Monaten konnte ich zum ersten Mal mit GitHub Copilot von Microsoft auf die Startbahn gehen. Ob der Flug erfolgreich war oder ob ich es gar nicht in die Luft geschafft habe, möchte ich euch einmal berichten.

## Was ist GitHub Copilot?
Der Copilot ist ein intelligenter Assistent, der euch beim Programmieren helfen soll. Dies erfolgt in der Form von Vorschlägen, die euch Copilot in Echtzeit während der Eingabe anzeigt.
Beim Copilot handelt es sich um eine Künstliche Intelligenz, die auf <a href="https://openai.com/blog/openai-codex/" target="_blank">OpenAI Codex </a> basiert. 


## Registrieren und Installieren  
Zunächst werfen wir einen Blick in den Registrierungs- und Installationsprozess. Als Erstes müsst ihr euch bei GitHub registrieren und dort eine Lizenz erwerben. Der Copilot ist leider nicht kostenlos. Es besteht aber die Möglichkeit das Tool zunächst 60 Tage lang zu testen. Danach kostet es 10 $ pro Monat oder 100 $ pro Jahr. 

Studierende haben die Möglichkeit, sich über die <a href="https://education.github.com/" target="_blank">GitHub-Education-Seite</a> zu registrieren und sich den GitHub-Pro-Account zu sichern. Darin sind einige Tools enthalten. Unter anderem <a href="https://docs.github.com/en/copilot/overview-of-github-copilot/about-github-copilot#about-billing-for-github-copilot" target="_blank">GitHub Copilot</a>, aber auch der Azure-Edu-Account mit 100 $ Startbonus (kann man sich durchaus mal anschauen). 

Nach der Registrierung müsst Ihr Copilot in eurer IDE als Plugin installieren.
Ich habe das ganze ausschließlich in IntelliJ und Android Studio genutzt, weshalb hier nur dieser Weg aufgezeigt wird. Neben den <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-a-jetbrains-ide" target="_blank">JetBrain IDEs </a>     steht euch Copilot auch noch in
<a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio-code" target="_blank">Visual Studio Code</a>, <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio" target="_blank">Visual Studio</a> und <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-neovim" target="_blank">Neovim</a> zur Verfügung.


GitHub stellt Copilot als Plugin bereit und ihr könnt ihn mit wenigen Klicks innerhalb der IDE im Pluginfenster installieren. 

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/yndDfMvaT5GtXHbwo03Q)

Ist das abgeschlossen, müsst ihr noch euren GitHub-Account mit der IDE verbinden! Hierdurch wird geprüft, ob ihr eine gültige Lizenz besitzt. Das Login-Fenster findet ihr (in IntelliJ) ganz unten rechts in der Taskbar. 

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/4csRilxRauicu6YEEO55" width="200" />

Danach könnt ihr direkt mit Programmieren anfangen und Copilot wird euch ab sofort Vorschläge geben.


## Wie funktioniert es in der IDE?

Nachdem Copilot eingerichtet ist, könnt Ihr mit der Benutzung starten. Der zunächst intuitive Anwendungsfall ist die Inline-Vervollständigung. Ihr habt eine bereits implementierte Funktion und wollt diese nun im Code aufrufen. Fangt ihr an, diese Funktion einzutippen, erscheint ein ausgegrauter Vorschlag. Das Besondere dabei ist, dass auch die Übergabeparameter mit syntaktisch korrekten Parametern vorgeschlagen werden.

**Du tippst:**
``` Kotlin
sumOf
```

**Vorschlag vom Copilot:**
``` Kotlin
sumOfTwoNumbers(2, 5)
```

Gefällt euch der Vorschlag nicht, habt ihr drei Möglichkeiten, damit umzugehen. 
Zum einen könnt Ihr mit der Tastenkombination `Option + [` bzw. `Option + ]` durch weitere Vorschläge iterieren. Natürlich nur sofern diese vorhanden sind. Zum anderen könnt Ihr den Vorschlag mit `Esc` ablehnen. 

Das Schönste an Copilot ist aber die Möglichkeit, weiterzuschreiben und ihn einfach zu ignorieren. Im Gegensatz zu anderen solcher Tools stört er fast nie. Warum fast nie? Weil es hin und wieder vorkommt, dass er mehrere Zeilen an Vorschlägen macht und sich somit der eigentliche Code nach unten bewegt. Will man aktuell gar nicht mit ihm arbeiten, glitscht es dann ein wenig. Aber das ist selten und stört in Summe nicht. 
Wollt ihr dennoch mal Ruhe von Copilot haben, könnt ihr ihn mit zwei Klicks leicht deaktivieren. Entweder komplett oder für einen bestimmen Dateityp. Das findet ihr am gleichen Ort wie für die Authentifizierung mit GitHub (in IntelliJ).

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8SawieNyROinyPIZE1Mn" width="200"/>


**Hier noch einmal die Shortcuts in der Zusammenfassung:**

| Aktion                | Windows / Linux | macOS       |
| --------------------- | --------------- | ----------- |
| Inline-Vorschläge     | Alt + \         | Option + \  |
| nächster Vorschlag    | Alt + ]         | Option + ]  |
| vorheriger Vorschlag  | Alt + \[        | Option + \[ |
| Vorschlag akzeptieren | Tab             | Tab         |
| Vorschlag ablehnen    | Esc             | Esc         |
 *In anderen IDEs können die Shortcuts abweichen


### Beispiele
Besonders positiv ist mir Copilot bei der Verwendung von Methoden mit vielen Parametern aufgefallen. Gerade beim Nutzen von Datenklassen, die dann in Mocks genutzt wurden, musste ich mir keine Dummy-Daten ausdenken – zum Beispiel beim Verwenden eines Personenobjekts.

``` Kotlin
data class Person(  
	val name: String,  
	val age: Int,  
	val isMarried: Boolean,  
	val children: List<Person>  
)
```
Jetzt gibt man nur  `Person` ein und Copilot schlägt dann etwas wie das folgende vor:
``` Kotlin
Person(  
	name = "John", age = 30, isMarried = true, children = listOf(  
		Person(  
			name = "Mary", age = 15, isMarried = false, children = listOf()  
		),   
		Person(  
			name = "Bob", age = 20, isMarried = false, children = listOf()  
		)  
	)  
)
```
Ok zugegeben, dass John mit 10 Jahren schon den Bob als Kind bekam, scheint nicht ganz realistisch. Hieran erkennt man aber auch die Grenze der KI.

Eine weitere Möglichkeit zur Generierung von Code ist das Schreiben von Kommentaren. Ihr könnt einfach beschreiben, was ihr haben möchtet und Copilot liefert euch einen oft ganz guten Ansatz. 

**Beispiel:**
``` Kotlin
// write a function, that can calculate the sum of 2 float values
```

**Copilot schlägt dann folgendes vor:**
``` Kotlin
fun sum(a: Float, b: Float): Float {  
	return a + b  
}
```

Ihr könnt auch auf anderen Sprachen als Englisch schreiben. Hier zum Beispiel mal zum Vergleich auf Englisch und Deutsch.
``` Kotlin
class Test(){  
//write a function, that takes a string and returns the first character of the string  
//if the string is empty, return null    

fun firstChar(str: String): Char? {  
    if (str.isEmpty()) {  
        return null  
    }  
    return str[0]  
}  
```
  
``` Kotlin
// schreibe eine Funktion, die einen string übergeben bekommt und den ersten Buchstaben des Strings zurückgibt  
// wenn der String leer ist, gib 5 zurück    

fun firstChar2(str: String): Char? {  
	if (str.isEmpty()) {  
		return '5'  
	}  
	return str[0]  
}  
```
*Den Return habe ich geändert, damit man erkennt, dass es unterschiedliche Vorschläge sind.

Copilot kann durchaus noch mehr. Hier sind vor allem auch kreative Ideen gefragt. Eine kleine Auflistung liefert GitHub im Artikel <a href="https://github.blog/2022-09-14-8-things-you-didnt-know-you-could-do-with-github-copilot/" target="_blank">8 things you didn’t know you could do with GitHub Copilot</a>.

## Copilot!
Das ganze wirkt durchaus beeindruckend und funktioniert erstaunlich vernünftig sowie stressfrei. Dennoch ist es nur eine Hilfe. Der Name Copilot ist Programm und sollte auch so verstanden werden. Im Kontext der Programmierung steuert der Pilot (das seid ihr) das Flugzeug (das Programm). Er entscheidet, wo es hingeht und er hält das Flugzeug auf Kurs. 

Copilot gibt dabei wertvolle Unterstützung beim Start, der Landung und dem Flug, ist aber nicht entscheidend für den Erfolg dieses Fluges. Verlasst euch niemals nur auf den Vorschlag von Copilot. Überprüft, was er vorschlägt und ob das ganze wirklich passt.

## Ein Blick hinter die Kulissen
Nach dem ersten positiven Hype, den ich beim Ausprobieren entwickelt habe, stellte ich mir die Frage, woher die Vorschläge eigentlich kommen. 

Zum einen stammen viele Vorschläge vom aktuelle Repository, in dem ich gerade arbeite. Es werden zum Beispiel bereits implementierte Klassen und Methoden erkannt und die Übergabeparameter "sinnvoll" vorgeschlagen. Soweit ist das nichts Neues und das gleiche Vorgehen wie auch bei anderen solcher Tools.

Jedoch werden auch Vorschläge für ganze Codeblöcke gemacht, die keineswegs von meinem Code stammen können. Ein Blick auf die Funktionsbeschreibung von Copilot verrät, dass die Quelle andere Repositories auf GitHub sind. Laut GitHub handelt es sich dabei um öffentlichen Repositories, anhand derer die KI trainiert wird. 

Codex versucht Strukturen und Pattern von existierendem Code zu finden und erzeugt daraus unter anderem diese Vorschläge.  Darin liegt die *Macht* von Github Copilot. 


##  Die Dunkle Seite der Macht
Neben all dem positiven gibt es auch eine Schattenseite. Wie schon erwähnt, generiert der Copilot seine Vorschläge anhand von öffentlichen Repositories. 

Und das ist der große Knackpunkt. Darf Microsoft einfach den Code von anderen Repositories nutzen und damit Profit generieren? Viele der auf GitHub gehosteten Projekte wurden unter einer <a href="https://de.wikipedia.org/wiki/Copyleft" target="_blank">Copyleft-Lizenz</a> lizenziert. Damit sind diese Projekte nicht gemeinfrei, sondern stehen unter der <a href="https://de.wikipedia.org/wiki/Free/Libre_Open_Source_Software" target="_blank">"Free and Open Source Software"-Lizenz (FOSS)</a>.

Nutzt man diese Projekte, muss man den oder die Autoren nennen. Außerdem gibt es die Option, dass Software, die auf Grundlage dieser Open-Source-Software basiert, ebenfalls unter einer Copyleft-Lizenz lizenziert werden muss. Das ganze geschieht bei der Nutzung von GitHub Copilot nicht. Rein rechtlich ist Microsoft hier wohl auf der sicheren Seite, aber einen faden Beigeschmack hat das Ganze dennoch.

Das ist ein komplexes Thema, welches schon <a href="https://www.heise.de/meinung/Edit-Policy-GitHubs-KI-Copilot-ist-keine-Urheberrechtsverletzung-6128502.html" target="_blank">in anderen Artikeln</a> gut beleuchtet wurde. Dieses Thema wird in den kommenden Jahren noch für viel Gesprächsstoff sorgen. Nicht nur GitHub Copilot stößt an Grenzen der Ethik und des Rechts. Auch anderer solcher Tools werden diese Probleme bekommen. Denn eine KI, die gut funktionieren soll, muss auch gut trainiert werden. Das bedeutet, dass es viele Daten braucht. Die Grenzen werden sich wohl Stück für Stück verschieben und ggf. müssen neue Regelungen geschaffen werden, damit der Open-Source-Gedanke weiter bestehen kann.


## Fun Fact
Ich schreibe den Blogbeitrag aktuell im IntelliJ mit Markdown. Und während ich diese Zeilen schreibe, schlägt mir der Copilot meine Satzvervollständigung vor.  
Wir probieren mal, was passiert, wenn ich ab jetzt nur noch das nehme, was Copilot vorschlägt. Ich markiere alles, was ich getippt habe, dick. Und Los gehts:  
  
> **Ha**llo, ich bin ein neuer Entwickler. GitHub ist ein tolles Tool. **Da**s ist ein COPILOT-Tool.  
> **Zum Ab**schluss: **sei nochmal gesa**gt, dass ich ein COPILOT-Tool bin.  
  
Naja, wie sinnvoll das in Textanwendungen ist, sei mal dahingestellt.  :) 

GitHub Copilot – Pair Programming mit der KI

P5.JS: Zeichnen mit der Open-Source-JavaScript-Bibliothek

ArchUnit in der Praxis: Architektur sauber halten und optimieren

# Modularisierung leicht gemacht: Spring Modulith mit Kotlin und Hexagonale Architektur

Modularisierung ist ein Schlüsselkonzept in der modernen Softwareentwicklung, um Anwendungen wartbar, testbar und flexibel zu gestalten. In diesem Artikel zeigen wir, wie Spring Modulith in Verbindung mit der hexagonalen Architektur und Kotlin eine solide Grundlage für die Modularisierung schaffen kann. Wir betrachten die Herausforderungen bestehender monolithischer Anwendungen und wie durch klar definierte Module eine schrittweise Entkopplung gelingt.

## Was ist ein Modulith?

Der Name deutet es schon an. Ein Modulith bezeichnet eine Architektur, bei der ein Monolith in klar abgegrenzte Module unterteilt wird. Diese Module sind so gestaltet, dass sie möglichst stark voneinander entkoppelt sind und interne Abhängigkeiten minimiert werden. Ihr könnt es euch so vorstellen, als ob ihr mehrere Microservices in ein Repository packt und unter einer Anwendung handhabt. Zum Beispiel könnte ein Modul die Benutzerdaten und ein anderes Modul die Rechnungsstellung verwalten, wobei beide Module klar voneinander getrennt sind, aber in derselben Anwendung laufen. Der Vorteil liegt auf der Hand: Es sind keine aufwendigen HTTP-Schnittstellen oder Kafka-Broker notwendig. Keine Authentifizierungen, um zwischen den Modulen zu kommunizieren, und dennoch ist der Vorteil einer losen Kopplung gegeben.

Modularisierung kann also als ein sanfter Einstieg in die Microservice-Welt gesehen werden.

## Was macht Spring Modulith

Um eine Anwendung in Module zu unterteilen gibt es verschiedene Optionen. Zum einen kann man einfach den Code in verschiedene Packages packen. Zum anderen bieten Maven bzw Gradle die Option Module mit eigenen Dependencies und eigenem Build-Script zu erzeugen. Und auch die Aufteilung in Microservices ist eine Art Modularisierung.

Schaut man sich die drei Optionen an, fällt auf, dass deren Umsetzung geordnet in ihrem Aufwand steigt. Während Pakete noch sehr einfach anzulegen sind, braucht es für Maven/Gradle-Module schon jeweils separate Dependency-Definitionen. Der Aufwand, Microservices in die Welt zu senden und deren Kommunikation untereinander zu ermöglichen, legt den anderen beiden noch einmal eine ganze Schippe oben drauf.

Wir wollen also eigentlich erst einmal nur mit Paketen starten. Aber hier bekommen wir schnell ein Problem. Stellt euch vor, ihr habt eine Legacy-Anwendung, bei der ein Domain-Modell auf das andere zugreift und das wiederum auf das nächste. Packt ihr nun alle eure passend zusammenhängenden Klassen in die jeweiligen Pakete, sieht es zwar nach verschiedenen Modulen aus, aber in Wirklichkeit ist dem nicht so.

Wir wollen eine lose Kopplung erreichen. Vom Prinzip her wollen wir vielleicht später mal in der Lage sein, eines der Module herauszulösen und als Microservice zu deployen. Dann wollen wir natürlich so wenig wie möglich Kopplung haben. Somit wird der Refactoring-Aufwand reduziert.

Leider sieht man diese Kopplung nur sehr schwer, da sie oft erst bei einer detaillierten Analyse des Quellcodes oder bei der Beobachtung von unerwartetem Verhalten in der Anwendung deutlich wird. Im Zweifel fällt es erst auf, wenn versucht wird, das Modul herauszulösen und als eigenen Microservice zu deployen. Häufig verbirgt sich diese Kopplung in subtilen Abhängigkeiten zwischen Modulen, die durch direkte Zugriffe entstehen. Selbst wenn ihr anfangt aufzuräumen und in einer großen Hauruck-Aktion die Klassen voneinander entkoppelt, werdet ihr spätestens in der weiteren Entwicklung wieder Kopplungen erhalten.

Und genau hier hilft Spring Modulith. Es prüft, ob ihr Dependencies von einem Modul auf ein anderes habt, welche nicht erlaubt sind.

## Grundlagen

Stellen wir uns vor, wir haben folgende Struktur:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── ModuleTwoService.kt

```

In unserem `src`-Package liegt also eine `Application.kt` und daneben zwei Pakete: `module-1` und `module-2`. In den beiden Modulen befindet sich zum einen ein Interface und ein Service, welcher die Implementierung des Interfaces darstellt.

Das Erste, was Spring Modulith macht, ist, alle Pakete, welche auf der gleichen Ebene liegen wie die `Application.kt`, als Modul zu definieren. Das passiert von ganz alleine, und ihr müsst dafür nichts weiter tun. Alle sich darin befindlichen Klassen und Interfaces werden von Spring Modulith standardmäßig als public angesehen. Es ist also erlaubt, von allen anderen Modulen auf diese Klassen zuzugreifen.

Nun wollen wir aber nicht, dass der `ModuleOneService` direkt auf den `ModuleTwoService` und vice versa zugreifen kann, sondern das Ganze soll nur über die Interfaces möglich sein. Um das zu erreichen, packen wir die Services einfach in ein Sub-Package:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── services
│       └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── services
        └── ModuleTwoService.kt

```

Greifen wir nun von einem der Services auf den anderen Service zu, wird der Spring Modulith-Test fehlschlagen.

## Spring Modulith Test

Da wir nun schon den Test erwähnt haben, möchte ich hier noch einmal kurz aufzeigen, wie diese Tests aussehen. Im Grunde stellt euch Spring Modulith drei "Test"-Funktionalitäten zur Verfügung. Zum einen haben wir den eigentlichen Test, der unsere Module analysiert und verifiziert, ob wir die lose Kopplung, die wir haben wollen, einhalten.

```kotlin
@Test
fun `verifies modular structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.verify()
}

```

Als Nächstes haben wir die Option, uns einmal die Module mit deren Definitionen anzuschauen. Hierin werden alle wesentlichen Inhalte eines Moduls wie zum Beispiel die `NamedInterfaces`, auf die wir gleich noch zu sprechen kommen, ausgegeben.

``` kotlin
@Test
fun `print module structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.forEach(Consumer { module: ApplicationModule? -> println(module) })
}

```

Und als Letztes bietet Spring Modulith die Möglichkeit, euch eine Doku zu generieren. Diese beinhaltet verschiedene PlantUML-Diagramme der Module und deren Beziehungen zueinander. Aber auch eine AsciiDoc-Dokumentation mit den Diagrammen und allen Klassen sowie Interfaces, welche nach außen öffentlich gemacht sind.

```kotlin
@Test
fun `create module documentation`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    Documenter(modules)
        .writeDocumentation()
        .writeIndividualModulesAsPlantUml()
}

```

## Hexagonale Architektur

Selten werden wir so einfache Strukturen in unseren Modulen haben, wie in dem Beispiel weiter oben zu sehen. Gerade wenn wir mit Strukturen wie der hexagonalen Architektur arbeiten, entstehen viele Sub-Packages. Einige von ihnen wollen wir ggf. nach außen hin zugänglich machen. Eine solche Struktur könnte dann so aussehen:

```toml
src
├── Application.kt
├── module-1
│   ├── adapter
│   │   ├── inbound
│   │   └── outbound
│   ├── domain
│   │   ├── services
│   │   │   └── ModuleOneService.kt
│   │   ├── model
│   │   └── ports
│   │       ├── inbound
│   │       │   └── ModuleOneInterface.kt
│   │       └── outbound
│   └── services
└── module-2
    ├── adapter
    │   ├── inbound
    │   └── outbound
    └── domain
        ├── services
        │   └── ModuleTwoService.kt
        ├── model
        └── ports
            ├── inbound
            │   └── ModuleTwoInterface.kt
            └── outbound

```

Nun können die Services weiterhin nicht auf andere Services zugreifen, da sie in einem Sub-Package liegen. Jedoch können die Services nun auch nicht mehr auf die Interfaces zugreifen, da diese nun ebenfalls in einem Sub-Package liegen. Wir müssen an dieser Stelle also klar definieren, dass wir zum Beispiel das Package `module-1.domain.ports.inbound` nach außen öffnen wollen. Dazu legt man in Java eine `package-info.java` in das Package und kann hier sein Package definieren.

In Kotlin funktioniert dieser Weg nicht. Hier müssen wir eine Klasse erstellen und dieser gewisse Annotationen mitgeben. Wir erzeugen uns also die `ModuleMetadata.kt` und legen sie in den zu definierenden Ordner. Der Name der Klasse ist dabei nicht von Bedeutung. Ihr könnt die Klasse auch `Drotbohm.kt` oder `Weihnachtsmann.kt` nennen. Viel wichtiger ist der Inhalt.

```toml
└── ports
    ├── inbound
    │   ├── ModuleOneInterface.kt
    │   └── ModuleMetadata.kt

```

Hier sind zwei Annotationen zu sehen: Zum einen `@PackageInfo` und `@NamedInterface`.

```kotlin
@PackageInfo
@NamedInterface(name = ["inbound-port"])
class ModuleMetadata

```

`@PackageInfo` ist in der Java-Variante nicht nötig, da dies durch den Dateityp bereits gegeben ist. In Kotlin wird dies benötigt, damit Spring Modulith weiß, dass es sich um die PackageInfo-Datei handelt und hier die Deklaration für das Package zu finden ist.

`@NamedInterface` definiert den Namen, unter dem das Package später von Spring Modulith gefunden werden kann. Auch diese Annotation ist nötig, ihr müsst jedoch keinen Namen angeben. Lasst ihr den Parameter weg, wird der Name des Packages genutzt. Wollt ihr einen expliziten Namen angeben, müsst ihr in Kotlin mit Named-Parametern arbeiten und das Ganze als Array definieren.

Der Name ist gerade in der hexagonalen Architektur nicht ganz unwichtig. Schaut ihr euch ein wenig weiter oben den Projektbaum an, werdet ihr feststellen, dass wir zwei Packages haben, welche `inbound` heißen. Einmal in der Domain und einmal in den Adaptern. Lasst ihr den Namen weg, werden beide Packages öffentlich gemacht, da sie den gleichen Namen besitzen.

## Explizite Zugriffe auf Module

Stellt euch vor, wir haben einige Module in unserer Anwendung. Wir haben in jedem dieser Module einige Packages öffentlich für andere Module gemacht.

Nun kann jedoch jedes Modul auf alle der geöffneten Packages aus allen anderen Modulen zugreifen. Das wollen wir aber nicht. Wir öffnen ein Package ja ggf. nur für ein spezifisches Modul. Auch hier kann man eine Definition vornehmen, um dies sicherzustellen.

Nehmen wir an, wir haben neben unseren `module-1` und dem `module-2` auch noch ein `module-3`. In allen drei Modulen haben wir gewisse Packages öffentlich gemacht. Nun wollen wir, dass `module-1` ausschließlich auf Packages von `module-2` zugreifen darf. Und innerhalb von `module-2` soll es auch nur auf das `inbound-port`-Package zugreifen dürfen.

Um das zu tun, erstellen wir wieder eine Module-Metadata in der obersten Ebene von `module-1`:

```toml
└── module-1
    ├── ModuleMetadata.kt
    ├── adapter
    │   ├── ...
    ├── domain
        ├── ...

```

In der `ModuleMetadata.kt` fügen wir nun die `@ApplicationModule`-Annotation hinzu. Hierin können wir dann über `allowedDependencies` die Module und Packages deklarieren, auf die das Modul Zugriff haben darf. Das Ganze erfolgt nach dem Schema: `Module :: Package`. Der Paketname ist entweder der Name des Packages, in dem eure `ModuleMetadata.kt` des anderen Moduls liegt, oder derjenige, den ihr in der `ModuleMetadata.kt` als NamedInterface deklariert habt.

```kotlin
@ApplicationModule(
    allowedDependencies = ["module-2 :: inbound-port"]
)
class ModuleMetadata

```

Wenn ihr weitere Module und/oder NamedInterfaces erlauben wollt, könnt ihr dies hier einfach kommasepariert angeben. Solltet ihr zwar ein Modul erlauben, aber keine Einschränkungen der einzelnen Packages wollen, könnt ihr dies mit dem Sternchen (`*`) ausdrücken: `allowedDependencies = ["module-2 :: *"]`.

## Legacy Anwendung

Nun wissen wir, wie wir einzelne Packages freigeben und den Zugriff auf diese für andere Module explizit angeben können. Setzen wir das Ganze in einer Legacy-Anwendung um, wird die Liste an Fehlern im Spring Modulith-Test sehr lang. Das alles mit einem Mal zu beheben, ist oft sehr aufwändig.

Aber auch hierfür bietet Spring Modulith eine Option, um euch auch beim Modularisieren von Legacy-Anwendungen zu unterstützen.

Ihr könnt in der Moduldefinition, in der ihr die `allowedDependencies` eingefügt habt, noch einen weiteren Parameter ergänzen. Und zwar den `type`. Mit diesem könnt ihr das gesamte Modul auf öffentlich setzen. Das heißt, alle Packages sind ab dann für alle anderen Module verfügbar, auch wenn ihr darin keine Module-Metadata definiert habt.

```kotlin
@ApplicationModule(
    type = ApplicationModule.Type.OPEN,
    allowedDependencies = ["module-1 :: inbound-port"]
)
class ModuleMetadata

```

Es ist also möglich, zunächst die Module mit ihrer Paketstruktur zu erstellen und die bis dato starke Kopplung noch zu behalten. Eure Tests bleiben weiterhin grün, ihr könnt andere Änderungen committen und eure Pipeline läuft sauber durch. Das ermöglicht euch, eure Module nacheinander zu entkoppeln. Die Öffnung eines Moduls sollte aber nur so lange Bestand haben, wie ihr euer Modul entkoppelt. Sobald das Modul entkoppelt ist, kann man den Typ entweder auf CLOSED setzen oder einfach aus der `@ApplicationModule`-Annotation entfernen.

## Fazit

Ein Modulith ist ein Monolith, der in klar abgegrenzte Module unterteilt wird, um lose Kopplung und bessere Wartbarkeit zu erreichen. Diese Module laufen zwar in einer gemeinsamen Anwendung, sind aber so strukturiert, dass sie weitgehend voneinander getrennt funktionieren. Gerade bei Legacy-Anwendungen, die viele unübersichtliche Abhängigkeiten aufweisen, bietet das modulare Konzept einen schrittweisen Übergang zu einer entkoppelten Architektur.

Spring Modulith unterstützt diesen Ansatz, indem es auf Packagings in einer Spring-Anwendung aufsetzt und automatisch Module erkennt. Im Default-Zustand sind alle Pakete eines Moduls öffentlich, doch über spezielle „Metadata“-Dateien können unerwünschte Abhängigkeiten blockiert oder nur bestimmte Bereiche (z.B. Interfaces) öffentlich gemacht werden. Das sorgt dafür, dass Zugriffe zwischen Modulen nur explizit erlaubt erfolgen.

Zur Überprüfung der modularen Struktur stellt Spring Modulith drei zentrale Test-Funktionen bereit:

1. **Verifikation**: Ein Test, der prüft, ob alle definierten Modulgrenzen eingehalten werden.
2. **Modul-Übersicht**: Eine Ausgabe der erkannten Module und deren Abhängigkeiten.
3. **Dokumentation**: Eine automatisierte Erzeugung von AsciiDoc-Dateien und PlantUML-Diagrammen.

Gerade bei komplexen Strukturen wie in der hexagonalen Architektur (Ports & Adapters) legen sich Services, Interfaces und Adapterschichten häufig in mehreren Sub-Packages ab. In Kotlin kennzeichnet man die öffentlichen Bereiche dann mit einer speziellen Klasse (z.B. `ModuleMetadata.kt`), die Spring Modulith mit den Annotationen `@PackageInfo` und `@NamedInterface` eindeutig identifiziert. Außerdem lässt sich der Zugriff anderer Module auf genau diese Bereiche durch `@ApplicationModule(allowedDependencies = […])` explizit steuern.

Für Legacy-Systeme, die sofortige Trennung in „saubere“ Module nicht erlauben, können einzelne Module auch offen deklariert werden (`type = ApplicationModule.Type.OPEN`). Dadurch bleiben vorhandene Abhängigkeiten vorerst bestehen. So lässt sich Schritt für Schritt vorgehen: Zuerst werden Module nur grob definiert, später werden einzelne Teile geschlossen, bis eine solide Modularisierung erreicht ist.

Mit diesen Bausteinen habt ihr alles an der Hand, um einen guten Einstieg in die Modularisierung mit Spring Modulith zu schaffen. 

Spring Modulith bietet neben den genannten Dingen auch noch weitere Funktionalitäten, wie Application Events, welche einen weiteren spannenden Aspekt darstellen. Da solltet ihr ebenfalls einen Blick hineinwerfen.

Eine kleine Anwendung, in der wir einige der Aspekte umgesetzt habe, findet ihr hier: [https://github.com/darthkali/spring-modulith-hex-test](https://github.com/darthkali/spring-modulith-hex-test)

##

Modularisierung leicht gemacht: Spring Modulith mit Kotlin und Hexagonale Architektur

Stellt euch eine Insel namens "Alistair Island" vor. Diese Insel ist ein lebendiger Ort mit Häusern, fruchtbaren Böden und einer eingespielten Gemeinschaft von Bewohnern, die nach klaren Abläufen leben. Jedes Geschehen auf der Insel ist von Bedeutung und dient einem bestimmten Zweck. Die täglichen Aufgaben und Rituale sind festgelegt, und die Insel funktioniert wie ein gut koordiniertes Ensemble.

Die Insel ist von einem Festland umgeben, auf dem verschiedene Länder mit unterschiedlichen Industrien und Bevölkerungsgruppen existieren. Diese produzieren unterschiedliche Waren, bieten diverse Dienstleistungen an und sprechen verschiedene Sprachen. Die Bewohner des Festlands sind vielfältig und umfassen Handwerker, Händler, Postboten und viele andere Berufe.

Nicht nur variieren die Sprachen und Waren der verschiedenen Gebiete des Festlands. Auch die Bewohner der Insel haben ihre eigene Sprache und eine einzigartige Kultur, die sich von allem auf dem Festland Bekannten unterscheidet.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wtcM9pkyTcezHMl9uucT)


Obwohl die Insel isoliert ist, gibt es zahlreiche Verbindungen zur Außenwelt. An verschiedenen Küstenpunkten befinden sich Häfen, die Handel und Kommunikation mit dem Festland ermöglichen. Für den Transport von Nachrichten, Gütern und weiteren legen Schiffe an den Häfen des Festlands und der Insel an.

Um den Handel geordnet abzuwickeln, existiert ein Handelsabkommen. Es legt fest, dass Schiffe, die Waren von der Insel zum Festland transportieren oder umgekehrt, bestimmte Handelsrouten nutzen müssen. Schiffe, die vom Festland zur Insel fahren, nutzen die Routen, welche westlich der Insel liegen, während Schiffe, die von der Insel zum Festland fahren, die östlichen Routen befahren.

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/B8LsrUXQQ6W1gNYjodYg)

Es gibt verschiedene Arten von Schiffen. Große Frachtschiffe sind beladen mit Lebensmitteln und Vorräten. Passagierschiffe bringen Besucher zur Insel. Kleinere Boote dienen dazu, spezielle Nachrichten und Aufträge zu überbringen.

Jedes Schiff hat einen Heimathafen. Schiffe, die auf den westlichen Handelsrouten fahren und vom Festland aus entsandt werden, legen an einem festgelegten Hafen am Festland an. Die Schiffe von der Insel warten an den Häfen der Insel, um ihre Reise anzutreten.

Entscheidend ist also nicht, in welche Richtung Waren oder Nachrichten übermittelt werden, sondern wer den Auftrag dazu gegeben hat. Betrachten wir das Ganze stets aus Sicht der Insel, so sind Schiffe, welche vom Festland aus kommen, eingehende Schiffe. Schiffe, die von der Insel entsandt werden, sind ausgehende Schiffe. Egal ob sie Waren liefern oder eine Anfrage senden  um Waren zu bekommen. Ein ausgehendes Schiff kann also durchaus die Intention haben, Waren vom Festland zur Insel zu transportieren. Dennoch gilt es als ausgehend, da die Intention von der Insel ausgeht.

Aufgrund der unterschiedlichen Sprachen der Inselbewohner und des Festlands müssen die Schiffe mit Übersetzern ausgestattet sein, um die Nachrichten des Festlands für die Inselbewohner verständlich zu machen. Auch die Güter müssen möglicherweise umverpackt werden, da auf dem Festland z. B. große Kräne zum Verladen genutzt werden, während auf der Insel alles händisch transportiert wird. Eine Qualitätsprüfung ist ebenfalls sinnvoll, um sicherzustellen, dass die Waren den Bedürfnissen der Insel entsprechen. Falls nicht, gibt das Schiff direkt Rückmeldung an das Festland. Das Ganze gilt selbstverständlich auch andersherum. Die ausgehenden Schiffe packen um, übersetzen und prüfen, ob die Waren für das Festland korrekt sind.

Die Schiffe sind die einzigen, die sowohl die Sprache der Insel als auch die des Festlands beherrschen und wissen, wie die Waren entsprechend umverpackt werden müssen. Sie sind jedoch nur für ihre jeweilige Handelsroute spezialisiert. Wenn neue Handelsrouten entstehen, kommt ein anderes Schiff zum Einsatz.

Ein weiterer wichtiger Aspekt dieser Welt ist die Stabilität der Insel. Die Stabilität der Insel bleibt, unabhängig von Änderungen der Güter oder des Baus neuer Häfen, erhalten. Lediglich die Art des Schiffes und dessen Besatzung müssen sich anpassen oder eine neue Handelsroute eingeführt werden. Die Bewohner der Insel erhalten ihre Waren und Nachrichten jedoch immer in der für sie gewohnten Art und Sprache.

So existiert Alistair Island, sicher und stabil, inmitten des weiten Ozeans. Ungeachtet neuer Schiffe oder Veränderungen auf dem Festland bleibt die Insel das, was sie ist: ein Ort voller Leben, Struktur und mit einer besonderen Verbindung zur Welt um sie herum.

<aside>

### 💡 Zusammenfassung

- Alistair Island ist eine isolierte Insel mit einer eigenen Kultur und klaren Abläufen.
- Die Insel steht in Verbindung mit einem Festland, das vielfältige Waren und Dienstleistungen bietet.
- Handelsabkommen regeln die Handelsrouten zwischen Insel und Festland.
- Schiffe, die vom Festland entsandt werden, gelten (aus Sicht der Insel) als eingehende Schiffe. Sie sind an den Häfen des Festlands stationiert und fahren immer auf den westlichen Handelsrouten.
- Schiffe, die von der Insel entsandt werden, gelten als ausgehende Schiffe. Sie sind an den Häfen der Insel stationiert und fahren immer auf den östlichen Handelsrouten.
- Es gibt verschiedene Schiffstypen, die jeweils spezifische Aufgaben übernehmen (Frachtschiffe, Passagierschiffe, kleine Boote).
- Übersetzer und Qualitätsprüfungen sind notwendig, um die Unterschiede zwischen Insel und Festland zu überwinden. Die spezialisierten Schiffe übernehmen diese Aufgabe.
- Die Stabilität der Insel bleibt gewahrt, unabhängig von äußeren Veränderungen oder neuen Handelsrouten.

</aside>

## Übertragung der Analogie in die Hexagonale Architektur

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mOt9dAJRMSHBA2o8wJdY)


Lasst uns nun die Analogie der Insel, Häfen und Schiffe in die Begriffe der hexagonalen Architektur übertragen, um ihre Zusammenhänge zu verdeutlichen.

### Insel - Domäne

![Finale Insel_komplett.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/I1eM0DTnS5S9rWiTKldh)


Die Insel in unserer Analogie repräsentiert die Domäne – den Kern der Geschäftslogik. Die Insel ist das Zentrum, in dem alle wichtigen Prozesse und Abläufe stattfinden, genauso wie die Domäne der Ort ist, an dem die Geschäftslogik verwaltet und verarbeitet wird.

### **Schiffe - Adapter** 

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vUKzCLWiRDHG9DKfKjNQ)


Die Schiffe in der Analogie stehen für die Adapter in der hexagonalen Architektur. Sie sorgen dafür, dass die Kommunikation zwischen der Außenwelt und der Domäne tatsächlich stattfinden kann. Sie sind spezialisierte Übersetzer, welche die Sprache zwischen der Domäne und der Außenwelt (in beide Richtungen) übersetzen.

Adapter sind also maßgeblich dafür verantwortlich, dass die Anforderungen von außen in eine Form gebracht werden, die im Inneren der Domäne verarbeitet werden kann. Zudem bringen sie auch die Anforderungen nach außen in eine Form, die von der Außenwelt verstanden werden kann. Zum Beispiel könnte ein eingehender Adapter eine REST-API-Anfrage in ein Domänenobjekt übersetzen, während ein ausgehender Adapter die Domänenobjekte in eine für Datenbankabfragen oder externe API-Aufrufe verständliche Form bringt.

Wir unterscheiden also zwischen eingehenden und ausgehenden Adaptern:

- **Eingehende Adapter** nehmen Aufträge von externen Systemen oder Aktoren (Festland) entgegen, übersetzen sie und stellen sie der Domäne bereit. Die eingehenden Adapter entsprechen den eingehenden Schiffen, die von den Häfen des Festlands starten, um auf die Insel zu gelangen.
- **Ausgehende Adapter** hingegen nehmen die Antworten oder Daten der Domäne und bereiten sie für externe Systeme oder Aktoren (Festland) auf, damit sie verständlich und nutzbar sind. Die ausgehenden Adapter sind die ausgehenden Schiffe, die an den Häfen der Insel bereitstehen, um Informationen von der Domäne zurück an das Festland zu transportieren.

Ob ein Adapter nun ein eingehender oder ausgehender ist, entscheidet maßgeblich, wer den Auftrag initial gegeben hat. Dabei schauen wir immer aus der Sicht der Domäne (Insel).

### **Häfen - Ports**

  ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/5B96iNZeQXmyC6FPzJv4)


Die Häfen, die wir in der Analogie verwendet haben, entsprechen in der hexagonalen Architektur den sogenannten Ports. Ports sind die klar definierten Schnittstellen, über die die Domäne, also der Kern der Geschäftslogik, sich von der Außenwelt abgrenzt. Dabei wird zwischen eingehenden und ausgehenden Ports unterschieden. Wir haben in der Analogie schon einmal erwähnt, dass die Schiffe ebenfalls in eingehende und ausgehende unterteilt werden. Dabei war wichtig, wer den Auftrag erteilt  und somit das Schiff entsendet hat. Die Ports (Häfen) bilden dies ebenfalls ab.

Zum Beispiel kann ein eingehender Port eine Bestellung aus einem Webshop entgegennehmen, während ein ausgehender Port Zahlungsinformationen an einen externen Zahlungsdienstleister übermittelt.

## Wie ist die Domäne aufgebaut?

Interessanterweise haben wir uns bisher kaum mit dem Innenleben der Insel selbst beschäftigt – also damit, wie die Bewohner agieren, welche Strukturen und Rituale sie pflegen. Beispielsweise könnte man sich fragen, wie sie Güter effizient verteilen, Entscheidungen im Konsens treffen oder Regeln für ein harmonisches Zusammenleben festlegen. Was machen sie mit den Gütern und Nachrichten? Wie sind die Wege in der Stadt, welche Regeln gibt es und wie werden diese eingehalten? Das liegt daran, dass die eigentliche Gestaltung der Domäne – also der Kern der Geschäftslogik – kein Bestandteil der hexagonalen Architektur ist.

Die hexagonale Architektur konzentriert sich ausschließlich auf die Gestaltung der Schnittstellen (Ports) und den zugehörigen Adaptern. Diese Fokussierung ist zentral, da sie sicherstellt, dass die Domäne unabhängig bleibt und flexibel auf Änderungen in der Außenwelt reagieren kann, ohne ihre interne Logik zu gefährden. Wie die Menschen auf der Insel miteinander interagieren, welche Regeln sie befolgen und wie die alltäglichen Prozesse ablaufen, wird durch andere Architekturprinzipien geregelt. Ein Konzept wie Domain-Driven Design (DDD) kann unter anderem dafür verantwortlich sein, wie die Domäne strukturiert wird. Ihr könnt euch auch eigene Prinzipien ausdenken oder einfach drauf los bauen – all das hat keinen direkten Einfluss auf die hexagonale Architektur und wird auch nicht von ihr vorgeschrieben.

Die wichtigste Regel der hexagonalen Architektur ist: Trennt die Domäne von der Außenwelt. Lasst die Bewohner der Insel autark arbeiten und leben, keine Änderung der Außenwelt darf direkten Einfluss auf die Bewohner der Insel haben.

# **Warum eigentlich ein Hexagon?**

Eine Frage, die bei Einsteigern in die hexagonale Architektur häufig aufkommt, ist: Warum ist es ein Hexagon? Braucht es immer sechs Elemente? Haben die gegenüberliegenden Seiten des Hexagons eine besondere Beziehung?

Die einfache, wenn auch etwas ernüchternde Antwort lautet: Es gibt keine tiefere Bedeutung hinter der Form des Hexagons. Alistair Cockburn, der diese Architektur konzipiert hat, fand die Form des Hexagons einfach spannend und wollte eine anschaulichere Bezeichnung für die Architektur als nur "Ports und Adapter". Tatsächlich ist "Ports und Adapter" der eigentlich korrekte Name für diese Architektur, aber er ist zu generisch und nicht besonders einprägsam.

Wie wir an dem Beispiel der Insel gesehen haben, funktioniert das Ganze auch mit komplett organischen Formen und braucht keine spezielle Geometrie. Das Hexagon ist nur ein symbolisches Mittel, um die unterschiedlichen Schnittstellen und Beziehungen anschaulicher darzustellen.

# **Vom Hafen zum Java Interface**

Ein kleiner Hinweis vorweg: Wer Sprachen wie JavaScript, Python und Co. nutzt, wird die Interfaces vergebens suchen. In solchen Sprachen gibt es diese Schnittstellen nur als implizite Signatur. Das Prinzip bleibt jedoch gleich, auch wenn dort die Schnittstellen nicht explizit als Interface erzeugt werden.

Nun wollen wir uns aber anschauen, wie wir das Ganze im Code umsetzen. Dazu schauen wir uns einmal das folgende Diagramm an.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vTwf2booQtmqkTNLN2B3)

Wie wir sehen, haben wir hier zwischen eingehenden und ausgehenden Adaptern unterschieden. Das sind unsere Schiffe, die zwischen dem Festland und der Insel hin- und herfahren.

Die Insel ist auch in Form der Domäne vorhanden. Diese beinhaltet die Services und die Ports. Anhand der Pfeile könnt ihr nun gut erkennen, wer wen nur nutzt und wer wen implementiert. Wichtig ist hierbei noch, dass der Outbound-Port zwingend notwendig ist, da er dafür sorgt, dass die Dependency umgedreht wird. Dies folgt dem **Dependency Inversion Principle**. Der Inbound-Port ist technisch nicht zwingend notwendig. Der Adapter kann ohne Weiteres direkt auf den Service zugreifen. Durch die Einführung von Interfaces erhaltet ihr jedoch eine losere Kopplung. Außerdem leidet die Testbarkeit ein wenig, wenn ihr direkt von dem Adapter auf den Service zugreift. In der Regel solltet ihr also auch auf der eingehenden Seite einen Port vorsehen.

Nun schauen wir uns noch kurz an, wie das Ganze im Code aussieht.

Wir gehen einmal davon aus, dass wir ein Framework nutzen, welches die Dependency Injection für uns übernimmt. Spring wäre hier ein gutes Beispiel. Dann ist das alles ganz einfach: Wenn eine Klasse ein Interface nutzt, dann gebt ihr es als Übergabeparameter in den Klassenkonstruktor mit.

```kotlin
//uses
@Service
class SomeService(private val forUsingPort: ForUsingPort){
	// what ever your service does
}

```

Implementiert eine Klasse nun ein Interface, dann tut ihr das, was der Name schon sagt. Ihr lasst die Klasse den Port (ForImplementingPort) implementieren. Das sieht dann so aus:

```kotlin
// implements
@Service
class SomeService(): ForImplementingPort{
	 override fun functionOfPort(){
		 // what ever you should do here
	 }
}
```

Und das ist es im Grunde auch schon.

# **Fazit**

Die hexagonale Architektur wird häufig als überladenes Konzept wahrgenommen, doch sie beruht auf wenigen klaren Prinzipien, die ihre Anwendung überraschend einfach machen.

- Trenne die Domäne von der Außenwelt. Die Geschäftslogik und Datenverarbeitung sollten  unabhängig von der Datenbank oder Webframeworks gestaltet werden. Damit sie leichter ausgetauscht oder erweitert werden können.
- Alles, was Technologie betrifft, sollte nicht in der Domäne sein.
- Füge Ports rund um deine Domäne hinzu, um die beiden anderen Punkte sicherzustellen.

Wenn diese Grundsätze einmal verstanden sind, lässt sich die hexagonale Architektur fast immer anwenden. Selbst in kleinen Projekten ist es sinnvoll, die Domäne frei von technischen Details zu halten, um sie einfacher testen zu können. Zum Beispiel kann eine Geschäftslogik, die keine direkte Abhängigkeit zu einer spezifischen Datenbank hat, leicht in isolierten Unit-Tests überprüft werden. Die hexagonale Architektur hilft dabei und eignet sich hervorragend zur Unterstützung dieser Trennung.

Ein Tipp zum Einstieg: Ein Tool wie ArchUnit kann euch helfen, eure Umsetzung mit Tests zu überprüfen. Falls ihr darüber mehr wissen möchtet, schaut bei meinem Blogbeitrag zu ArchUnit vorbei: [ArchUnit in der Praxis: Architektur sauber halten und optimieren](https://www.codecentric.de/wissens-hub/blog/archunit-in-der-praxis-architektur-sauber-halten-und-optimieren)

Hexagonale Architektur ist auch nur eine Insel

ArchUnit in practice: Keep your Architecture Clean

# Modularization the easy way: Spring Modulith with Kotlin and Hexagonal Architecture

Modularization is a key concept in modern software development to make applications maintainable, testable and flexible. In this article we will see how Spring Modulith combined with hexagonal architecture and Kotlin provides a solid foundation for modularization. We will examine the challenges of existing monolithic applications and how clearly defined modules enable step-by-step decoupling.

## What is a Modulith?

The name says it all. A Modulith refers to an architecture where a monolith is divided into clearly defined modules. These modules are designed to be as decoupled from each other as possible while minimizing internal dependencies. You can think of it as bundling multiple microservices into a single repository and managing them as one application. For example one module could manage user data and another could handle invoicing. Both modules running in the same application but remaining distinctly separated. The advantage is clear: there is no need for complex HTTP interfaces or Kafka brokers, no authentication for inter-module communication and yet the benefit of loose coupling is maintained.

Modularization can therefore be seen as a gentle introduction to the microservices world.

## What Does Spring Modulith Do?

To divide an application into modules, there are various options. One approach is simply to organize the code into different packages. Another is to use Maven or Gradle to create modules with their own dependencies and build scripts. Additionally splitting an application into microservices is another form of modularization.

When comparing these three options it becomes apparent that their implementation effort increases progressively. While packages are easy to organize, Maven/Gradle modules already require separate dependency definitions. Deploying microservices and enabling their communication with each other adds even more complexity.

We actually want to start with packages initially. But here we run into a problem quickly. Imagine you have a legacy application where one domain model accesses another and vice versa. Even if you group logically related classes into packages it may look like different modules but it’s not really the case.

We aim for loose coupling. Ideally, we should ne able to extract a module  later and deploy it as a microservice. In that sense, we want minimal coupling which reduces refactoring effort.

Unfortunately, this coupling is hard to detect as it often only becomes evident through detailed code analysis or when observing unexpected application behavior. In the worst case, it only becomes apparent when trying to extract a module and deploy it as a standalone microservice. Such coupling often hides in subtle interdependencies between modules arising from direct accesses. Even if you clean up and decouple classes in one big action, coupling will creep back during further development.

This is where Spring Modulith helps. It checks whether you have dependencies between modules that are not allowed.

## Basics

Let’s assume we have the following structure:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── ModuleTwoService.kt

```

In our `src` package, there is an `Application.kt` and alongside it two packages: `module-1` and `module-2`. Each module contains an interface and a service that implements the interface.

The first thing Spring Modulith does is to define all packages at the `Application.kt` level. This happens automatically without requiring any additional configuration. All classes and interfaces in these packages are by default considered public by Spring Modulith allowing other modules to access them.

Now, we don’t want `ModuleOneService` to directly access `ModuleTwoService` and vice versa; access should only be possible through the interfaces. To achieve this, we simply place the services in a subpackage:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── services
│       └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── services
        └── ModuleTwoService.kt

```

If one service now tries to access another one, the Spring Modulith-Test will fail.

## Spring Modulith Test

Since we’ve mentioned the test let’s briefly explore what these tests look like. Spring Modulith provides three main “test”-functionalities. First, there’s the actual test that analyzes our modules and verifies if we maintain the desired level of loose coupling.

```kotlin
@Test
fun `verifies modular structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.verify()
}

```

Next we have the option to inspect the modules and their definitions. This outputs the key contents of each module such as `NamedInterfaces`, which we’ll discuss shortly.

```kotlin
@Test
fun `print module structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.forEach(Consumer { module: ApplicationModule? -> println(module) })
}

```

Also Spring Modulith can generate a documentation. This includes various PlantUML diagrams of the modules and their relationships as well as AsciiDoc documentation with diagrams and all publicly exposed classes and interfaces.

```kotlin
@Test
fun `create module documentation`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    Documenter(modules)
        .writeDocumentation()
        .writeIndividualModulesAsPlantUml()
}

```

## Hexagonal Architecture

Rarely will our modules have simple structures like the example above. Especially when working with an architectural style like hexagonal architecture. There we have many sub-packages. Some of which we may want to expose externally. Such a structure might look like this:

```toml
src
├── Application.kt
├── module-1
│   ├── adapter
│   │   ├── inbound
│   │   └── outbound
│   ├── domain
│   │   ├── services
│   │   │   └── ModuleOneService.kt
│   │   ├── model
│   │   └── ports
│   │       ├── inbound
│   │       │   └── ModuleOneInterface.kt
│   │       └── outbound
│   └── services
└── module-2
    ├── adapter
    │   ├── inbound
    │   └── outbound
    └── domain
        ├── services
        │   └── ModuleTwoService.kt
        ├── model
        └── ports
            ├── inbound
            │   └── ModuleTwoInterface.kt
            └── outbound

```

Services still cannot access other services as they are in a subpackage. However, they also cannot access the interfaces as they are now in a subpackage as well. Here, we must explicitly define that for instance, the `module-1.domain.ports.inbound` package should be externally accessible. In Java, this is done by creating a `package-info.java` file in the package.

In Kotlin this approach doesn’t work. Instead, we create a class and annotate it. For example, we create a `ModuleMetadata.kt` file and place it in the respective package. The class name is irrelevant. You could name it `Drotbohm.kt` or `SantaClaus.kt`. The content is what matters.

```toml
└── ports
    ├── inbound
    │   ├── ModuleOneInterface.kt
    │   └── ModuleMetadata.kt

```

Here are two annotations: `@PackageInfo` and `@NamedInterface`.

```kotlin
@PackageInfo
@NamedInterface(name = ["inbound-port"])
class ModuleMetadata

```

`@PackageInfo` is unnecessary in the Java version since it is implicitly provided by the file type. In Kotlin it is required for Spring Modulith to recognize it as the package declaration file.

`@NamedInterface` defines the name under which the package will be recognized by Spring Modulith. This annotation is also required but you can omit the name parameter. In this case the package name will be used. If you want to specify a name explicitly you must use named parameters and define it as an array.

The name is particularly important in hexagonal architecture. Looking at the project tree above we see two packages named `inbound`, one in the domain and one in the adapters. Without a specified name both packages are exposed as they share the same name.

## Explicit Module Access

Imagine we have several modules in our application, each exposing some packages to other modules.

Now any module can access all exposed packages from all other modules. Thats not what we want. Instead, we want to expose a package only for specific modules. This can also be defined.

Suppose we have `module-1`, `module-2`, and `module-3`. Each has some exposed packages. We want `module-1` to access only the packages from `module-2` and within `module-2` only the `inbound-port` package.

To achieve this we create a `ModuleMetadata.kt` file at the top level of `module-1`:

```kotlin
└── module-1
    ├── ModuleMetadata.kt
    ├── adapter
    │   ├── ...
    ├── domain
        ├── ...

```

In `ModuleMetadata.kt` we add the `@ApplicationModule` annotation. Here we can declare the modules and packages the module is allowed to access using `allowedDependencies`. The schema is `Module :: Package`. The package name is either the name of the package containing the `ModuleMetadata.kt` of the other module or the name defined as a NamedInterface in the `ModuleMetadata.kt`.

```kotlin
@ApplicationModule(
    allowedDependencies = ["module-2 :: inbound-port"]
)
class ModuleMetadata

```

If you want to allow additional modules and/or NamedInterfaces, you can list them separated by commas. If you wish to allow a module but impose no restrictions on individual packages, you can use an asterisk (`*`): `allowedDependencies = ["module-2 :: *"]`.

## Legacy Application

Now that we know how to expose specific packages and explicitly declare module access, let’s apply this to a legacy application. In this case the list of errors in the Spring Modulith-Test might be long. Fixing everything at once is often impractical.

However, Spring Modulith offers an option to support modularizing legacy applications.

In the module definition, where you’ve added `allowedDependencies`, you can also add a `type` parameter. This allows you to make the entire module public, meaning all packages are accessible to all other modules even without Module-Metadata definitions.

```kotlin
@ApplicationModule(
    type = ApplicationModule.Type.OPEN,
    allowedDependencies = ["module-1 :: inbound-port"]
)
class ModuleMetadata

```

This makes it possible to create modules with their package structures while maintaining strong coupling temporarily. Your tests remain green, commits can proceed and your pipeline continues to run. This enables gradual decoupling of modules. However this approach should only remain until the module is being decoupled. Once the module is decoupled the type can be set to CLOSED or removed from the `@ApplicationModule` annotation.

## Conclusion

A Modulith is a monolith that is divided into clearly defined modules to achieve loose coupling and improved maintainability. While these modules run in a single application, they are structured so that they operate largely independently. Particularly for legacy applications with many tangled dependencies, this modular concept provides a gradual transition toward a more decoupled architecture.

Spring Modulith supports this approach by building on packaging within a Spring application and automatically detecting modules. By default, all packages of a module are public, but special “metadata” files can block unwanted dependencies or make only certain areas (such as interfaces) public. This ensures that access between modules only occurs if it is explicitly allowed.

To verify the modular structure, Spring Modulith provides three key test functions:

1. **Verification**: A test that checks whether all defined module boundaries are respected.
2. **Module Overview**: An output displaying the detected modules and their dependencies.
3. **Documentation**: Automated generation of AsciiDoc files and PlantUML diagrams.

Especially in more complex structures, such as those found in hexagonal architecture (Ports & Adapters), services, interfaces and adapter layers are often split into multiple sub-packages. In Kotlin you mark the public areas with a special class (e.g., `ModuleMetadata.kt`) that Spring Modulith recognizes through the `@PackageInfo` and `@NamedInterface` annotations. Additionally, you can explicitly control how other modules access these areas by using `@ApplicationModule(allowedDependencies = […])`.

For legacy systems that do not allow an immediate separation into “clean” modules, individual modules can also be declared as open (`type = ApplicationModule.Type.OPEN`). This way existing dependencies remain in place for the time being. You can proceed step by step: first defining modules only roughly and then gradually restricting certain parts until a solid modularization is achieved.

With these building blocks, you have everything you need to get started with modularization using Spring Modulith.

Beyond these features, Spring Modulith also offers other functionalities, such as Application Events—another exciting aspect worth exploring.

A small application where we have implemented some of these aspects can be found here: [https://github.com/darthkali/spring-modulith-hex-test](https://github.com/darthkali/spring-modulith-hex-test).

Modularization the easy way: Spring Modulith with Kotlin and Hexagonal Architecture

Imagine an island called "Alistair Island." This island is a vibrant place with houses, fertile soil, and a well-coordinated community of residents who live by well-defined routines. Every activity on the island has significance and serves a specific purpose. Daily tasks and rituals are established, and the island functions like a well-coordinated ensemble.

The island is surrounded by a mainland where various countries with diverse industries and populations exist. These countries produce different goods, offer a range of services and speak different languages. The inhabitants of the mainland are diverse including craftsmen, merchants, postal workers, and many other professions.

Not only do the languages and goods of the different regions of the mainland vary, but the island's residents also have their own language and a unique culture distinct from anything known on the mainland.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wtcM9pkyTcezHMl9uucT)

Although the island is isolated, there are numerous connections to the outside world. At various coastal points, harbors facilitate trade and communication with the mainland. Ships dock at the harbors of both the mainland and the island to transport messages, goods and other stuff.

To ensure organized trade, a trade agreement is in place. It specifies that ships transporting goods from the island to the mainland or vice versa must use designated trade routes. Ships traveling from the mainland to the island use the routes west of the island, while ships traveling from the island to the mainland take the eastern routes.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/B8LsrUXQQ6W1gNYjodYg)

There are various types of ships. Large cargo ships are loaded with food and supplies. Passenger ships bring visitors to the island. Smaller boats are used to deliver specific messages and fulfill special assignments.

Each ship has a home harbor. Ships traveling on the western trade routes and dispatched from the mainland dock at designated mainland harbors. Ships from the island wait at the island’s harbors to embark on their journey.

The key distinction lies not in the direction of goods or messages but in who initiated the request. Viewing everything from the island’s perspective, ships coming from the mainland are considered inbound ships. Ships dispatched from the island are outbound ships. Whether they deliver goods or make requests to get goods. An outbound ship might even intend to transport goods from the mainland to the island, yet it is classified as outbound since the intent originates from the island.

Due to the different languages spoken by the islanders and mainlanders, ships must be equipped with translators to make the mainland's messages understandable for the islanders. Goods may also need to be repackaged. For example large cranes might be used for loading on the mainland, while everything is transported manually on the island. Quality checks are also advisable to ensure the goods meet the island’s needs. If not, the ship provides immediate feedback to the mainland. This process works the other way around as well. Outbound ships repackage, translate and verify that goods destined for the mainland are appropriate.

The ships are the only ones capable of understanding both the language of the island and that of the mainland as well as how to repackage goods accordingly. However, they are specialized for their respective trade routes. When new trade routes emerge, different ships are deployed.

Another important aspect of this world is the stability of the island. The island's stability remains intact regardless of changes in goods or the construction of new harbors. Only the type of ship and its crew need to adapt, or new trade routes need to be established. The islanders continue to receive their goods and messages in the manner and language they are used to.

Thats how the Alistair Island exists secure and stable in the middle of the vast ocean. Despite the emergence of new ships or changes on the mainland the island remains what it is: a place full of life, structure and a unique connection to the world around it.

<aside>

### 💡 Summary

- Alistair Island is an isolated island with its own culture and well-defined routines.
- The island is connected to a mainland that offers a wide range of goods and services.
- Trade agreements regulate the trade routes between the island and the mainland.
- Ships dispatched from the mainland are considered inbound ships (from the island's perspective). They are stationed at mainland harbors and always use the western trade routes.
- Ships dispatched from the island are considered outbound ships. They are stationed at the island's harbors and always use the eastern trade routes.
- There are different types of ships, each taking on specific tasks (cargo ships, passenger ships, small boats).
- Translators and quality checks are necessary to bridge the differences between the island and the mainland. Specialized ships handle these tasks.
- The stability of the island remains intact, regardless of external changes or the introduction of new trade routes.

</aside>

## Transferring the Analogy to Hexagonal Architecture

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mOt9dAJRMSHBA2o8wJdY)

Let’s now transfer the analogy of the island, harbors and ships into the terms of hexagonal architecture to clarify their relationships.

### Island - Domain

![Finale Insel_komplett.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/I1eM0DTnS5S9rWiTKldh)

The island in our analogy represents the domain – the core of the business logic. The island is the center where all critical processes and routines take place, just as the domain is the place where business logic is managed and executed.

### **Ships - Adapters**

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vUKzCLWiRDHG9DKfKjNQ)

Ships in the analogy represent the adapters in hexagonal architecture. They ensure that communication between the external world and the domain can actually take place. These ships act as specialized translators that convert the "language" between the domain and the external world in both directions.

Adapters are therefore crucial in transforming external requests into a format the domain can process.  In addition they translate internal domain responses into a format the external world can understand. For example, an inbound adapter might translate a REST API request into a domain object, while an outbound adapter might convert domain objects into a format suitable for database queries or external API calls.

We distinguish between inbound and outbound adapters:

- **Inbound adapters** receive requests from external systems or actors (the mainland), translate them and pass them to the domain. These correspond to inbound ships which depart from the harbors of the mainland to reach the island.
- **Outbound adapters** on the other hand take the responses or data from the domain and prepare them for external systems or actors (the mainland) in a comprehensible and usable way. These correspond to outbound ships stationed at the island’s harbors ready to transport information from the domain back to the mainland.

Whether an adapter is inbound or outbound is determined primarily by who initiated the request. The perspective is always that of the domain (the island).

### Harbors **- Ports**

  ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/5B96iNZeQXmyC6FPzJv4)

The harbors we used in the analogy correspond to what are known as ports in hexagonal architecture. Ports are the clearly defined interfaces that separate the domain, the core of the business logic, from the external world. A distinction is made between inbound and outbound ports. As mentioned in the analogy, ships are also divided into inbound and outbound, depending on who issued the order and dispatched the ship. Ports reflect this concept as well.

For example, an inbound port might receive an order from a webshop, while an outbound port might send payment information to an external payment provider.

## How is the domain structured?

Interestingly we have so far barely touched on the inner workings of the island itself. How the residents act, what structures and rituals they maintain. For instance one might ask how they efficiently distribute goods, make decisions by consensus or establish rules for harmonious coexistence. What do they do with the goods and messages? How are the paths in the city organized, what rules exist and how are they enforced? This is because the actual design of the domain, the core business logic, is not part of hexagonal architecture.

Hexagonal architecture focuses exclusively on designing the interfaces (ports) and their corresponding adapters. This focus is essential as it ensures that the domain remains independent and can adapt flexibly to changes in the external world without compromising its internal logic. How the people on the island interact, what rules they follow and how everyday processes function are governed by other architectural principles. Concepts like Domain-Driven Design (DDD) can play a role in structuring the domain. Alternatively, you could devise your own principles or simply build as you go. None of this directly affects hexagonal architecture and is not dictated by it.

The most important rule of hexagonal architecture is: **Separate the domain from the external world.** Let the island's residents work and live autonomously. No change in the external world should directly impact the island's inhabitants.

# Why a hexagon?

A common question among beginners in hexagonal architecture is: Why a hexagon? Does it always need six elements? Do the opposite sides of the hexagon have a special relationship?

The simple, although somewhat underwhelming, answer is: there is no deeper meaning behind the hexagonal shape. Alistair Cockburn, who conceptualized this architecture, simply found the hexagon visually appealing and wanted a more illustrative name for the architecture than just "Ports and Adapters." In fact "Ports and Adapters" is the correct name for this architecture but it’s too generic and not particularly memorable.

As we’ve seen in the island analogy the concept also works with completely organic shapes and doesn’t require any specific geometry. The hexagon is merely a symbolic tool to make the different interfaces and relationships more visually comprehensible.

# From the harbor to the Java interface.

A quick note upfront: If you’re using languages like JavaScript, Python and similar you won’t find interfaces as explicit constructs. In these languages interfaces exist only as implicit signatures. However the principle remains the same even though interfaces are not explicitly defined.

Now, let’s take a look at how to implement this in code. To do so, we’ll examine the following diagram.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vTwf2booQtmqkTNLN2B3)

As we can see we have distinguished between inbound and outbound adapters. These are our ships traveling back and forth between the mainland and the island.

The island is also represented in the form of the domain. This includes the services and ports. Based on the arrows, you can clearly see who depends on whom and who implements what. It’s important to note that the outbound port is essential because it ensures the dependency is inverted. This follows the **Dependency Inversion Principle**. The inbound port however is not technically mandatory. The adapter can directly access the service without issues. But by introducing interfaces you achieve loser coupling. Additionally, testability suffers slightly if the adapter directly accesses the service. Therefore, you should typically also define a port on the inbound side.

Now let’s briefly look at how this appears in code.

Let’s assume we are using a framework that handles dependency injection for us such as Spring. This makes everything straightforward: If a class **uses** an interface, you simply pass it as a constructor parameter in the class.

```kotlin
//uses
@Service
class SomeService(private val forUsingPort: ForUsingPort){
	// what ever your service does
}
```

When a class **implements** an interface, it does exactly what the name suggests: the class implements the port (ForImplementingPort). It looks like this:

```kotlin
// implements
@Service
class SomeService(): ForImplementingPort{
	 override fun functionOfPort(){
		 // what ever you should do here
	 }
}
```

And that's it basically.

# Conclusion

Hexagonal architecture is often perceived as an overly complex concept but it is based on a few clear principles that make its application surprisingly simple:

- Separate the domain from the external world. Business logic and data processing should be designed independently of the database or web frameworks so they can be more easily replaced or extended.
- Anything related to technology should not reside within the domain.
- Add ports around your domain to ensure the first two points are upheld.

Once these principles are understood, hexagonal architecture can be applied in almost any situation. Even in small projects it is beneficial to keep the domain free of technical details to make it easier to test. For instance, business logic with no direct dependency on a specific database can be easily verified with isolated unit tests. Hexagonal architecture supports this separation and is an excellent tool for maintaining it.

**A tip for getting started:** A tool like ArchUnit can help you verify your implementation with tests. If you'd like to know more, check out my blog post on ArchUnit: [ArchUnit in practice: Keep your Architecture Clean](https://www.codecentric.de/wissens-hub/blog/archunit-in-practice-keep-your-architecture-clean)

Hexagonal Architecture is just an island

IT-Consultant & Entwickler

IT-Consultant & Developer

Stuttgart | Team

Vielen Dank für deine Anfrage. Ich melde mich bei dir.

Vielen Dank für deine Anmeldung. Eine E-Mail zur Bestätigung ist zu dir unterwegs.

Diese Seite ist eine Vorschau. \nKlicken Sie hier\n, um den Vorschaumodus zu verlassen.

Zu deiner Suche haben wir leider keine passenden Blogartikel gefunden. 

Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.

Du hast Fragen oder möchtest dich mit mir austauschen? Gern - trag einfach deine Kontaktdaten ein.

Die \nDatenschutzerklärung\n der codecentric AG habe ich zur Kenntnis genommen und bestätige das mit der Absendung des Formulars.*

Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.

Ich möchte eure Inhalte abonnieren. Diese Einwilligung kann ich jederzeit widerrufen bzw. den Blog Newsletter abbestellen. Die Datenschutzerklärung habe ich gelesen. Ich bin damit einverstanden, dass die codecentric AG, Hochstr. 11, 42697 Solingen, mich über eigene Dienstleistungen, branchenrelevante Events, Webinare und Publikationen der codecentric AG über die von mir angegebene E-Mail-Adresse informiert. Meine Einwilligung ist freiwillig. Ich kann meine Einwilligung jederzeit mit Wirkung für die Zukunft widerrufen (z.B. über den hierfür vorgesehenen Abmeldelink in unserem Newsletter, per E-Mail an datenschutz@codecentric.de oder per Post an die oben genannte Adresse der codecentric AG) erklären. Weitere Hinweise zur Verarbeitung meiner personenbezogenen Daten und zu meinen Rechten als betroffene Person finde ich hier: \nhttps://www.codecentric.de/datenschutzerklaerung\n

Bitte wähle deine/n gewünschte/n Standort/e aus.

Wir möchten dich als Mensch kennenlernen. Erzähle uns, wer du bist, worauf du Wert legst, wie du gerne arbeitest und was du von uns als Arbeitgeber erwartest.

Bitte füge deine Bewerbungsunterlagen ​(mind. Lebenslauf, gerne auch mehr)​​ ​als eine ​PDF-​Datei ​hinzu.

Es gilt die Datenschutzerklärung der codecentric AG, abrufbar unter \nDatenschutzbestimmungen\n. Mit dem Absenden des Formulars bestätige ich, dass ich diese zur Kenntnis genommen habe.

Job application form field placeholder 10

Keine passende Rolle gefunden? Bewirb dich bitte trotzdem initiativ! Jenseits von starren Schubladen zählen für uns vielmehr Motivation, Kompetenz und der Cultural Fit.

Job application form field placeholder 11

Dies ist ein Pflichtfeld, bitte fülle es aus.

Willkommen im Team Stuttgart

Jetzt für unseren Newsletter anmelden