Wir sind eine zertifizierte B Corporation.

Cloud-Native

Data & KI

Produktentwicklung

Resilienz & IT-Security

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

International contact

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?  

Senior Solution Architect / Head of API Consulting

Events: betterCode API

API Sprawl in der Ära des Great Unbundling: Herausforderungen und Strategien

<p>In Softwareentwicklungsprojekten steht man immer wieder vor der Frage, wie denn das jeweilige Projekt in vollem Umfang dokumentiert werden könnte. In der Regel nimmt man meistens Confluence oder ein anderes Wiki zur Hand. Aber warum entwickeln wir die Dokumentation des Projekts nicht direkt am Code? Zu diesem Zweck möchte ich euch in diesem ersten Teil der Artikelserie <a href="http://jbake.org/" target="_blank">JBake</a>  ein wenig näher bringen.<br /> JBake ist eigentlich ein Generator für statische Webseiten. Dan Allen, Project Lead des Asciidoctor-Projekts, bezeichnet es als „Jekyll of the JVM“. Anhand von Plugins für Maven und Gradle lässt sich JBake auf relativ einfache Art und Weise in Build Pipelines integrieren.<br /> Ich möchte nun anhand eines Beispiels die Einsatzmöglichkeiten von JBake erläutern. Zu allererst werden wir ein einfaches Gradle-Projekt bauen, um eine Ausgangsbasis für die weiteren Schritte zu schaffen.</p>

```
group 'de.codecentric.dk.afgd'
version '1.0-SNAPSHOT'

apply plugin: 'groovy'
apply plugin: 'java'

sourceCompatibility = 1.8

repositories { 
   mavenCentral()
   jcenter()
}

dependencies {
   compile 'org.codehaus.groovy:groovy-all:2.3.11'
   testCompile group: 'junit', name: 'junit',version: '4.12'
}

```

<p>Nun wird die Build-File um das Plugin <em>jbake-gradle-plugin</em> erweitert.</p>

```
plugins {
     id 'org.jbake.site' version '1.0.0'
}

```

<p>Dadurch erhalten wir nun einen weiteren Task „bake“, der es uns erlaubt, Dokumentation zu „backen“. Desweiteren benötigen wir hierzu noch eine JBake-Basisinstallation innerhalb der Sourcen. Unter dem MacOS-Betriebssystem lässt sich dies leicht mit SDKMAN (</p>

```
$ sdk install jbake
```

<p>) oder Homebrew (</p>

```
$ brew install jbake
```

<p>) erledigen.</p><p>Standardmäßig erwartet das Gradle-Plugin die Dokumentationsquellen unter <em>src/jbake</em>. Mit Parametern im Build-File lässt sich der Quell- und Zielort aber anpassen, wobei das Ziel immer im Build-Ordner liegt. In unserem Fall mit den folgenden Werten:</p>

```
jbake {
     srcDirName = 'src/documentation'
     destDirName = 'documentation'
}

```

<p>Da nun JBake installiert ist, kann im Verzeichnis</p>

```
src/documentation
```

<p>der Befehl</p>

```
jbake -i
```

<p>ausgeführt werden. Die so entstandene Struktur lässt sich nun nach Belieben erweitern und anpassen. Als Inhalt lassen sich im content-Ordner HTML-, Asciidoctor- oder Markdown-Dateien hinterlegen. Im Rahmen des Blogartikels wird die vorhandene Datei <em>about.html</em> durch <em>about.adoc</em> ersetzt und der Inhalt entsprechend angepasst.</p>

```
= Project documentation
Daniel Kocot
2017-10-03
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

```

<p>Innerhalb des Asciidoctor-Dokuments können JBake-Metainformationen hinterlegt werden, wie Seitentyp, Tags und der Status der jeweiligen Seite. Letzterer regelt die Sichbarkeit der Seiten nach dem „Backprozess“. Wem das Standardtemplate nicht gefällt, kann dieses mittels der Templatesprachen Freemaker, Groovy Simple, Groovy Markup, Thymeleaf und Jade seinen Wünschen nach anpassen.<br /> Wenn wir nun zurück auf den Buildprozess schauen, können wir zum Abschluss dieses ersten Teils den Build-Task mit dem Bake-Task verbinden.</p>

```
build.dependsOn bake

```

<p>Wenn wir nun den Build-Task ausführen, wird auch die Dokumentation erstellt. Im zweiten Teil werden wir weitere Zutaten für eine agile, frisch gebackene Dokumentation hinzufügen.</p><p>Eine Demo findet ihr in meinem Git-Repository <a href="https://gitlab.com/danielkocot/agile-fresh-baked-docs">agile-fresh-baked-docs</a> .</p>

Agile, frisch gebackene Dokumentation – Teil 1: JBake

<p>Nachdem wir uns im <a href="https://blog.codecentric.de/2017/10/jbake-agile-dokumentation-teil-1/" target="_blank">ersten Teil</a>  mit der Konfiguration von JBake beschäftigt haben, möchte ich in diesem Blogpost das Szenario um PlantUML erweitern.<br /> PlantUML ermöglicht es, UML-Diagramme in einfacher textueller Notation zu beschreiben.</p><table><tbody><tr><td>

```
@startuml
start
:Hello world;
stop
@enduml

```

</td><td><img src="https://media.graphassets.com/lMPuOCPQ9Ku40co6J1DC" alt="Result of " /></td></tr></tbody></table><p>Wir wollen nun PlantUML zu allererst in das bestehende Gradle Buildfile integrieren. Hierzu benötigen wir AsciidoctorJ-Diagram als externe Bibliothek für das Buildscript. Die Konfiguration von JBake muss für die Verwendung der asciidoctorj-diagram-Bibliothek angepasst werden. Die Bibliothek AsciidoctorJ-Diagram ermöglicht es nun, PlantUML-Diagramme innerhalb des Asciidoctor-Dokuments zu verwenden.</p>

```
buildscript {
    repositories {
        mavenCentral()
        jcenter()
    }
 
    dependencies {
        classpath 'org.asciidoctor:asciidoctorj-diagram:1.5.4.1'
    }
}
 
plugins {
     id 'org.jbake.site' version '1.0.0'
}
 
group 'de.codecentric.dk.afgd'
version '1.0-SNAPSHOT'
 
apply plugin: 'groovy'
apply plugin: 'java'
 
sourceCompatibility = 1.8
 
repositories {
    mavenCentral()
    jcenter()
}
 
dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.3.11'
    testCompile group: 'junit', name: 'junit', version: '4.12'
}
 
jbake {
    srcDirName = 'src/documentation'
    destDirName = 'documentation'
    configuration['asciidoctor.option.requires'] = "asciidoctor-diagram"
    configuration['asciidoctor.attributes'] = [
            "sourceDir=${projectDir}",
            "imagesDir=diagrams",
            "imagesoutdir=${bake.input}/assets/diagrams"
    ]
}

build.dependsOn bake

```

<p>Nun erstellen wir innerhalb des <i>content</i>-Ordners eine neue Datei <i>architecture.adoc</i>. Der Inhalt der Datei kann dem nachfolgenden Code-Block entnommen werden.</p>

```
= Architecture documentation
Daniel Kocot
2017-11-20
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

== First draft

[plantuml, "first_draft", "png"]
----
node "Confluence as content repository" as nodeconf
folder Intranet{
    together {
        node "WordPress Node 1" as nodeiwp1
        node "WordPress Node 2" as nodeiwp2
        node "WordPress Node 3" as nodeiwp3
        node "WordPress Node 4" as nodeiwp4
    }
}
folder Extranet{
    together {
        node "WordPress Node 1" as nodeewp1
        node "WordPress Node 2" as nodeewp2
        node "WordPress Node 3" as nodeewp3
        node "WordPress Node 4" as nodeewp4
    }
}
node "LoadBalancer / nginx Intranet" as lbinginx
node "LoadBalancer / nginx Extranet" as lbenginx
node "Content Delivery Network" as cdn
cloud "Intranet" as intranet
cloud "Extra/Internet" as internet
actor "Internal User" as internal
actor "External User" as external
nodeconf --> nodeiwp1
nodeconf --> nodeiwp2
nodeconf --> nodeiwp3
nodeconf --> nodeiwp4
nodeconf --> nodeewp1
nodeconf --> nodeewp2
nodeconf --> nodeewp3
nodeconf --> nodeewp4
nodeewp1 <--> lbenginx
nodeewp2 <--> lbenginx
nodeewp3 <--> lbenginx
nodeewp4 <--> lbenginx
nodeiwp1 <--> lbinginx
nodeiwp2 <--> lbinginx
nodeiwp3 <--> lbinginx
nodeiwp4 <--> lbinginx
cdn <--> nodeconf
cdn --> nodeewp1
cdn --> nodeewp2
cdn --> nodeewp3
cdn --> nodeewp4
cdn --> nodeiwp1
cdn --> nodeiwp2
cdn --> nodeiwp3
cdn --> nodeiwp4
lbinginx <--> intranet
lbenginx <--> internet
external <--> internet
internal <--> intranet
----

```

<p>Nachdem wir den ersten Draft für unser Architekturdiagramm in das Dokument geschrieben haben, bleibt nun die Frage, wie aus den Textinhalten nun eine Grafik wird.</p><p>Hierzu wird beim Erstellen der gesamten Dokumentation im ersten Schritt per PlantUML nun ein Bild, in unserem Fall im PNG-Format, generiert. Dieses wird im Assets-Ordner mit dem Namen <em>first-draft</em> und der Dateiendung .png gespeichert. In einem zweiten Schritt erstellt JBake nun die entsprechende HTML-Datei auf Basis der Asciidoctor-Datei.</p><p>Durch die Integration von PlantUML sind wir in die Lage versetzt, auch die wichtigen Architekturdiagramme nah am Quellcode zu pflegen. Im dritten Teil dieser Reihe werden wir einen Blick auf Testreports und deren Integration in JBake werfen.</p><p>Eine Demo findet ihr in meinem Git-Repository <a href="https://gitlab.com/danielkocot/agile-fresh-baked-docs">agile-fresh-baked-docs</a> .</p>

Agile, frisch gebackene Dokumentation – Teil 2: PlantUML mit JBake

<p>In den ersten beiden Teilen habe ich <a href="https://blog.codecentric.de/2017/10/jbake-agile-dokumentation-teil-1/" target="_blank">JBake</a>  und die Integration von <a href="https://blog.codecentric.de/2017/11/agile-frisch-gebackene-dokumentation-teil-2-plantuml-mit-jbake/" target="_blank">PlantUML</a>  vorgestellt. Nun möchte ich mich dem Thema Testautomatisierung und Dokumentation widmen. Hierzu wird Spock als Testframework in den vorhandenen Stack integrieren.</p><h2>Was ist denn nun Spock? Und warum ein weiteres Testframework?</h2><p>Spock ist in der JVM-Sprache Groovy geschrieben und nutzt eine eigene Domain-Specific Language (DSL) für die Beschreibung der Tests. Genau diese DSL fördert die Übersichtlichkeit und Lesbarkeit der Tests.  Natürlich lässt sich auch reiner Java-Code mit Spock ausführen.<br /> Eine weitere Besonderheit von Spock ist die Darstellung von fehlgeschlagenen Tests. Hiermit wird die fehlgeschlagene Bedingung bis in ihre Einzelkomponenten visualisiert.</p><h2>Von der Anforderung über den Test zur „getesteten“ Dokumentation</h2><p>Jeder Test in der Softwareentwicklung entsteht aus einer Anforderung heraus. In der Regel extistieren diese Anforderungen in einem Wiki. Wie kann der Entwickler auf direkte Änderung der Anforderung innerhalb eines Sprints reagieren? Lassen sich Anforderungen auch durch Product Owner ohne Entwicklungshintergrund als „as Code“ abbilden?<br /> Um das beschriebene Ziel zu erreichen, kommt Gherkin, eine sogenannte „Business Readable DSL“, zum Einsatz. Gherkin ist eine zeilenorientierte Sprache, welche Einrückungen für die Strukturierung benutzt.</p><p></p><p>Mittels eines selbst geschriebenen Gradle-Tasks können nun die einzelnen Gherkin-Specifications in Spock-Specifications transformiert werden. Für den Blogpost umfasst der Gradle-Task nur die Transformation der einfachsten Gherkin-Struktur.</p><p></p><p>Das Groovy-Skript stellt eine erste Basisumsetzung der Gherkin-Spezifikation dar. Durch Gherkin können wir nun einen Workflow zwischen dem Produkt Owner und den Entwicklern umsetzen, der zu weniger Iterationen zwischen einer Anforderung und deren Umsetzung innerhalb eines Sprints beitragen kann.</p><p>Wenn nun der Entwickler aufgrund der transformierten Anforderungen die testgetriebene Entwicklung mittels Spock vorantreibt, stellt sich die Frage, wie wir die Ergebnisse mit JBake abbilden können. Hierzu werden wir Spock Reports verwenden.<br /> Mit Spock Reports haben wir die Möglichkeit, die Ergebnisse des Spock Tests mit Hilfe von Templates in AsciiDoc darzustellen. Um diese Templates anpassen zu können, müssen wir eine <em>properties</em>-Datei unter <em>test/resources</em> anlegen.</p><p></p><p>In der Version 2.6 von JBake ist es nun möglich mittels einer <em>.jbakeignore</em> möglich, Dateien bei Dokumentationserstellung auszuschließen. Dieses Feature benutzen wir nun für die Erstellung der Testreports, da diese über ein <em>include</em> eingebunden werden. Wir möchten aber nicht, dass diese inkludierten Dateien als separate HTML-Dateien erstellt werden, sondern dass deren Inhalte einfach innerhalb der index.html eingefügt werden. Um dies innerhalb des kontinuierlichen Prozesses zu erreichen, muss ein Gradle Task für die Erstellung der ignore-Datei erstellt werden.</p><p></p><p>Dieser Task soll nun nach dem Gradle Test Task ausgeführt werden, was wir durch die Verwendung von <em>test.finalizedBy(createjbakeignorefile)</em> erreichen.</p><p>Ausgelöst durch den Test-Task innerhalb des Gradle Build wird der Report direkt in das Quellverzeichnis der Dokumentation geschrieben, und durch den Eintrag <code>build.finalizedBy(bake)</code> wird die Dokumentation mit JBake zum Ende des Builds erzeugt.<br /> Auf diesem Wege werden die getesteten Anforderungen nun ein fester Bestandteil der Dokumentation.</p>

Agile, frisch gebackene Dokumentation – Teil 3: Getestete Anforderungen mit JBake

<p>Im <a href="https://www.codecentric.de/wissen/softwerker/" target="_blank">Softwerker</a>  Spezial „Cloud Native“ und in seinem englischsprachigen Blogpost hat Benjamin Wilms eine Einführung zu „<a href="https://blog.codecentric.de/en/2018/07/chaos-engineering/" target="_blank">Chaos Engineering</a> “ gegeben. Aber wie gehen wir jetzt mit den möglichen Experimenten und deren Ergebnissen im jeweiligen Unternehmenskontext um?</p><p>Ich möchte euch den Chaos Engineering GameDay als entsprechende Plattform vorstellen. Hierbei geht es darum, dass wir in einem abgesicherten Rahmen (Raum und Zeit) erfahren, wie wir mit einem Ausfall in der Produktion „überleben“ können. GameDays sind so gesehen nichts anderes als Feuerübungen. Wie bei jeder Übung steht am Anfang die Überlegung, was geübt werden soll. Wollen wir den Ausfall des Datenbanksystems oder einer Hauptkomponente des Systems?</p><p>Um ein Gefühl für die Durchführung eines GameDay zu bekommen, sollte zu Beginn der Radius des Experiments sehr klein gewählt werden. Ebenso ist es ratsam, den GameDay erst innerhalb einer Testumgebung zu erproben. Somit sind wir bereit für einen GameDay auf der Produktion und können diesen in seiner Gesamtheit vorbereiten.</p><p>Das Wichtigste bei der Durchführung des Chaos Engineering GameDay ist die Kommunikation. Als erstes richten wir ein <i>Command Center</i> ein. Dieses kann sowohl ein virtueller Chat als auch ein Konferenzraum sein. Wichtig ist, dass jeder in diesem Raum Einblick in Erfolg, Abbruchkriterien und sämtliche sonstige Übersichten, die für den GameDay relevant sind, erhält. Nur so ist zu gewährleisten, dass potentielle Fehlerquellen schnell entdeckt werden. Wenn etwas schiefgeht, sollten ein Plan zur Wiederherstellung und eine Reihe von Abbruchbedingungen bereitliegen.</p><p>Bevor wir nun in den eigentlichen GameDay eintauchen, hier auch noch einmal die Regeln für Chaos Engineering, wie sie bereits von Benjamin Wilms aufgezeigt wurden.</p><ol><li>Sprich mit deinen Kollegen über deine geplanten Chaos-Experimente – vorher!</li><li>Wenn dir die Konsequenzen deines Chaos-Experiments bekannt sind, lass es!</li><li>Chaos ist keine Überraschung, du stellst deine Hypothese unter Beweis.</li><li>Chaos Engineering hilft dir, deine verteilten Systeme besser zu verstehen.</li><li>Begrenze den Radius deiner Chaos-Experimente.</li><li>Sei immer Herr der Lage während deines Chaos-Experiments!</li></ol><h2>Der Chaos Engineering GameDay im Detail</h2><p>Ein GameDay dauert zwischen zwei und vier Stunden. Im Idealfall sollten neben den Entwicklern und Operations auch die „Kunden“ der Applikation an dem geplanten Event teilnehmen. Doch was ist nun noch alles neben dem eigentlichen Experiment vorzubereiten?</p><p>Jeder GameDay braucht ein konkretes Ziel, auf das das Experiment angewendet werden kann. Über das Ziel definieren sich die jeweiligen Teilnehmer dann selbst. Nämlich aus der Tatsache heraus, ob sie sich angesprochen fühlen oder nicht. Neben dem definierten Ziel gilt es die Hypothese mit Testfällen belegbar zu machen.<br /> Aber bevor wir unser definiertes Ziel unter Druck setzen, sollten wir vorab zwei Dinge erledigen. Nach der Eröffnung des GameDay verbringen wir ein wenig Zeit mit der Darstellung der aktuellen Systemarchitektur, am besten auf einem Whiteboard zentral im Raum. Dies soll vor allem dafür sorgen, dass alle Teilnehmer den aktuellen Stand des Systems für ihre weiteren Überlegungen vor Augen haben. Gemeinschaftlich werden nun potentielle Testfälle überlegt. Für einige Tests kann es entscheidend sein, diese nicht über die tatsächliche Zeit zu betrachten. Wir wissen ja schon aus unserer Erfahrung, dass manche Applikationen nicht innerhalb eines bestimmten Zeitintervalls in Fehler laufen. Gerade wenn wir die Tests in Produktion durchführen, ist es umso wichtiger, dass wir eine Abbruchbedingung definieren.</p><p>Die Tests sind nun definiert, also können wir auch loslegen. Während des Durchlaufs des Tests ergeben sich einige Fragen. Falls sich diese zufriedenstellend beantworten lassen, ist der nächste Test an der Reihe. Hier nun einige Beispiele:</p><ul><li><i>Haben wir genügend Informationen?</i></li><li><i>Haben wir genau dieses Verhalten erwartet?</i></li><li><i>Was sieht der Kunden, während dies eintritt?</i></li><li><i>Was passiert vor- und nachgelagert der betrachteten Komponente?</i></li></ul><p>Wenn nun alle Tests durchgelaufen sind, können wir zu einer kurzen Zusammenfassung kommen. Diese Zusammenfassung stellt auch gleichzeitig den Abschluss des GameDay dar, wobei dies auch ein paar Tage lang betrachtet werden kann. So kann gewährleistet werden, dass alle Beteiligten die Ereignisse und Ergebnisse der Tests mit etwas Abstand betrachten können. Zuallererst wäre es ratsam, den Fokus auf die eklatanten Tests mit den entsprechenden Ergebnissen zu richten. Als Ergebnis der Diskussion werden die entdeckten Fehler über ein Ticketsystem an die entsprechenden Personen zur Klärung und Behebung weitergereicht. Aber auch alle anderen Tests sollten noch einmal näher betrachtet werden, um beispielsweise zu klären, ob diese gegebenenfalls vorher schon einmal negativ aufgefallen sind. Ebenfalls ist zu überlegen, ob sich diese positiven Tests auf irgendeine Art und Weise automatisieren lassen, um zukünftige Releases gegen Regression zu schützen.</p><p>Als Fazit lässt sich festhalten, dass ein GameDay schon einige Erkenntnisse zu einer Applikation bzw. Komponente liefern kann. Aber die kontinuierliche Durchführung wird zu erhöhter Sicherheit beim Betrieb von verteilten Applikationen und Komponenten führen. Wenn euch die Idee des GameDay gefällt, könnt ihr für den Anfang auch das Ganze ohne ein Experiment starten. Oftmals reicht es ja einfach schon aus, dass sich die richtigen Menschen im einem Raum treffen und die eine oder andere Frage stellen. Durch entstehende Diskussion und Nachdenken wird dann schon manch wichtige Erkenntnis gewonnen.</p><p>Ich hoffe, dass euch dieser Blogpost einen ersten Einblick in die Durchführung eines Chaos Engineering GameDay gegeben hat. Wenn ihr weitere Fragen, Anregungen und vielleicht Wünsche bezogen auf das Thema „Chaos Engineering“ habt, postet diese bitte in den Kommentaren.</p>

Chaos Engineering GameDay

<p>Wenn wir uns mit agiler Softwareentwicklung beschäftigen, sprechen wir grundsätzlich auch über Application Lifecycle Management (<em>ALM</em>). Ebenso treibt das Business, das hinter allen Anforderungen für die Entwicklung von Software steht, immer die Frage nach Wertschöpfung um. Damit wir euch Antworten auf eure Fragen geben können, müssen wir die Werte von ALM mit den Methodiken von Business Intelligence (<em>BI</em>) in Einklang bringen. Und genau aus diesem Aspekt möchte ich mich in diesem Post theoretisch mit der Wortschöpfung „<em>Application Lifecycle Intelligence</em>“ auseinandersetzen.</p><h2>Was verbirgt sich hinter dem Begriff <em>Business Intelligence?</em></h2><p>Laut dem Gabler Wirtschaftslexikon ist BI ein „<em>Sammelbegriff für den IT-gestützten Zugriff auf Informationen, sowie die IT-gestützte Analyse und Aufbereitung dieser Informationen. Ziel dieses Prozesses ist es, aus dem im Unternehmen vorhandenen Wissen neues Wissen zu generieren. Bei diesem neu gewonnenen Wissen soll es sich um relevantes, handlungsorientiertes Wissen handeln, das Managemententscheidungen zur Steuerung des Unternehmens unterstützt.</em>“</p><p>Um nun Methodiken von BI anwenden zu können, benötigen wir noch Metriken. Eine Metrik ist, laut IEEE Standard 612.10, <em>ein quantitatives Maß für den Grad, zu dem ein System, eine Komponente oder ein Prozess ein bestimmtes Attribut besitzt.</em></p><p>Aus den Metriken werden dann mit der Zeit und im Lauf eines Prozesses die Key Performance Indicators (<em>KPIs</em>). Diese geben an, was wichtig für das Team und den Business Case ist. Ebenso dienen sie auch als Grundlage für Trendberechnungen.</p><h2>Ist Agilität messbar?</h2><p>Wir bewegen uns ja in einem agilen Umfeld. Genau dieser Umstand stellt aber auch die größte Hürde bei der Messbarkeit dar. Nach den agilen Prinzipien ist die funktionierende Software die primäre Messgröße. Es ergeben sich aber auch sprachliche Schwierigkeiten, bezogen auf das Verständnis von Messbarkeit im Team. In der Regel treffen wir dort auf drei Typen: die Entwickler, den Product Owner (<em>PO</em>) und meist auch noch zusätzlich auf einen Projektmanager (<em>PM</em>). Alle drei haben ein grundlegend anderes Verständnis bezogen auf den Satz „Das Projekt läuft gut“. Die Entwickler verstehen darunter, dass die Softwarelösung gut durchdacht und entwickelt wurde. Für den PO wurden alle Features eines Sprints ausgeliefert. Und der PM ist der Ansicht, dass das Projekt gut in der Zeit und im Budget liegt.</p><p>Eine weitere Herausforderung der Agilität bezogen auf die Messbarkeit ist die Fokussierung auf ein Produkt und nicht auf Projekt. Die Idee von Agilität besteht ja darin ein funktionierendes Produkt auszuliefern und nicht ein Projekt abzuschließen. In der Regel vermischen sich im Projektalltag genau diese Sichtweisen, da das Projektmanagement grundsätzlich zahlengetrieben funktioniert.</p><h2>Daten des Software Development Life Cycle</h2><p>Wenn wir nun den Software Development Life Cycle (<em>SDLC</em>) betrachten, sind die Daten über einzelne Tools verteilt. Eine einheitliche Sicht wird dadurch erschwert. Bei den Tools der Firma Atlasssian gibt es durch die vorhandene Integrationsmöglichkeit der einzelnen ein erster Ansatz, der aber mit Sicht auf die Daten und deren Lage eher rudimentär ist. Wir wollen uns nun mit den folgenden genannten Systemen, aber ohne die Nennung eines konkreten Produkts, beschäftigen:</p><p><a href="https://media.graphassets.com/y8rY3dVQSioCo5bJd6ow"><img src="https://media.graphassets.com/y8rY3dVQSioCo5bJd6ow" alt="Application Lifecycle Intelligence - Agile Entwicklungssystemlandschaft" width="300" height="176" /></a> </p><p>Diese einzelnen Systeme beantworten unterschiedliche Fragestellungen.</p><p><a href="https://media.graphassets.com/TnaVZhOJRTGshudZOfGG"><img loading="lazy" src="https://media.graphassets.com/TnaVZhOJRTGshudZOfGG" alt="Application Lifecycle Intelligence - Fragen einfacher Datenlagen" width="301" height="179" /></a> </p><p>Die Fragen, die sich aus den jeweiligen Datenlagen ergeben, sind somit sehr kleinteilig. Wenn wir nun Datenlagen zusammenfassen, bekommen wir ein größeres Bild und können auch detailliertere Fragen stellen.</p><p><a href="https://media.graphassets.com/SRikkJNSSZek9YwkadC2"><img loading="lazy" src="https://media.graphassets.com/SRikkJNSSZek9YwkadC2" alt="Application Lifecycle Intelligence - Fragen kombinierter Datenlagen" width="300" height="178" /></a> </p><p>Für weitere und zugleich noch gezieltere Fragestellungen müssen wir die jeweiligen Datenlagen noch mehr miteinander in Verbindung bringen. Hierzu kann eine Mindmap zur Visualisierung der Zusammenhänge eine konkrete Hilfe sein.</p><p><a href="https://media.graphassets.com/dTvR4KsDQM2RsvgKiVOH"><img loading="lazy" src="https://media.graphassets.com/dTvR4KsDQM2RsvgKiVOH" alt="Application Lifecycle Intelligence - Fragestellung per Mindmap" width="300" height="137" /></a> </p><p>Nachdem wir uns Gedanken zu möglichen Fragestellungen gemacht haben, ist es nun an der Zeit, dass wir versuchen an die konkreten Daten aus den beteiligten Systemen zu gelangen. In der heutigen Zeit haben Systeme, die sich mit Themen des SDLC bzw. ALM beschäftigen eine gut dokumentierte Rest-API. Genau über diese APIs bekommen wir nun die Informationen, die wir für das weitere Vorgehen benötigen.</p><p>Aber welche Daten bekommen wir von den Systemen geliefert?</p><table><thead><tr><th>System</th><th>Datenlagen</th></tr></thead><tbody><tr><td>PVS</td><td><ul><li>Was?</li><li>Wann?</li><li>Wer?</li><li>Rohdaten müssen mit detailierten Informationen angereicht werden</li><li><em>Definition of Done</em> sollte klar und deutlich definiert sein</li></ul></td></tr><tr><td>VKS</td><td><ul><li>Wer verändert den Sourcecode?</li><li>Wer ünterstützt hier wen?</li><li>Das Verhältnis von Pull Requests, Commits und Kommentaren</li><li>Abgelehnte Pull Requests gegenüber zusammengeführten Pull Requests</li></ul></td></tr><tr><td>CI/CD</td><td><ul><li>Wie diszipliniert arbeitet das Team?</li><li>Wie häufig wird ausgeliefert?</li><li>Wie gut ist die Code-Qualität</li><li>Wie ist das Verhältnis von erfolgreichen und fehlgeschlagenen Builds?</li><li>Was sagen die Test Reports?</li><li>Welche Werte liefert die Code Coverage?</li></ul></td></tr><tr><td>AM</td><td><ul><li>Statistiken zum Zustand der Applikation zeigen wie gut diese gebaut ist</li><li>Willkürliche Werte und semantisches Logging dienen dazu, zu erfahren, wie eine Applikation wirklich genutzt wird</li></ul></td></tr></tbody></table><h2>Aus Daten werden Metriken</h2><p>Nachdem wir die Datenlagen der einzelnen Systeme betrachtet haben, können wir nun erste einfache Metriken zusammenfügen.</p><p><a href="https://media.graphassets.com/18nfpdc4RzWgRhDvetq1"><img loading="lazy" src="https://media.graphassets.com/18nfpdc4RzWgRhDvetq1" alt="Application Lifecycle Intelligence - Einfache Metriken" width="300" height="177" /></a> </p><p>Sobald wir die Bedeutung der einzelnen Werte verstanden haben, werden wir in die Lage versetzt komplexere Metriken durch Kombination dieser Werte und auch durch Hinzunahme weiterer Datenlagen zu entwerfen. Doch dazu müssen die neu geschaffenen Daten erst in eine normalisierte Form gebracht werden. Auch hier können Mindmaps den Herleitungsprozess unterstützen.</p><p>Es ist aber zu beachten, dass jegliche Änderung von Prozessen auch eine Anpassung der Metriken erfordert. Somit gelangen wir auch auf der Ebene der Daten und Metriken in einen kontinuierlichen Prozess.</p><p><a href="https://media.graphassets.com/NlGPnIaaTcg6eKRKFMu6"><img loading="lazy" src="https://media.graphassets.com/NlGPnIaaTcg6eKRKFMu6" alt="Application Lifecycle Intelligence - Kontinuierlicher Entwicklungsprozess einer Metrik" width="300" height="200" /></a> </p><p>Nun wollen wir uns einmal eine komplexe Metrik überlegen. Aufgrund der Tatsache, dass wir uns in einem kontinuierlichem Entwicklungsprozess befinden, möchten wir nun wissen, wie sich die Qualität der Releases in der fortlaufenden Entwicklung verändert. Zu aller erst bekommt unsere neue Metrik einen aussagekräftigen Namen, „<strong>Kontinuierliche Releasequalitätsbewertung</strong>“ (<em>KRQB</em>). Nun schauen wir unsere bekannten Metriken an und entscheiden uns für die <strong>Rückfälligskeitsquote</strong> (<em>RFQ</em>). Des Weiteren interessieren wir uns für die <strong>Anzahl der veränderten Zeilen Sourcecode</strong> (<em>VZS</em>). Die dritte Größe, die wir benötigen, ist der sogenannte <strong>Gesundheitsfaktor der Schätzungen</strong> (<em>GFS</em>). Dieser stellt in normalisierter Form die Genauigkeit aller Schätzungen dar. Der letzte Wert, der unser Interesse für die Erstellung weckt sind die <strong>entgangenen Fehler</strong> (<em>EF</em>). Bei den entgangenen Fehlern handelt es sich um die Fehler, die nicht während des Testens, sondern erst in der Produktion, aufgefallen sind.</p><p><a href="https://media.graphassets.com/VwQ97xUXTIyiYBFnvfa4"><img loading="lazy" src="https://media.graphassets.com/VwQ97xUXTIyiYBFnvfa4" alt="Application Lifecycle Intelligence - Berechnung KRQB" width="300" height="132" /></a> </p><p>Nachdem wir Metriken, einfach oder komplex, erstellt haben, stehen wir vor der Herausforderung diese innerhalb einer Organisation zu veröffentlichen. Hierbei müssen wir als erstes klären, für wen wir die Informationen zur Verfügung stellen wollen. Denn diese Personen müssen auf Grundlage der Metriken handeln können, somit erzeugen wir auch die entsprechenden KPIs.</p><p>Wenn wir nun die Personen in drei verschiedene Publikumsebenen zusammenfassen, ergibt sich die folgende Übersicht.</p><table><thead><tr><th>Ebene</th><th>Metriken</th></tr></thead><tbody><tr><td>Team</td><td><ul><li>Verhältnis von Pull Requests und Commits</li><li>Verhältnis von Aufgabenablaufquote und Rückfälligkeitsquote</li><li>Verhältnis von erfolgreichen und fehlgeschlagenen Buildvorgängen</li><li>Kundenorientierte Qualitätsbewertung</li></ul></td></tr><tr><td>Manager</td><td><ul><li>Durchlaufzeit</li><li>Entwicklungsgeschwindigkeit</li><li>Gesundsfaktor der Schätzungen</li><li>Verhältnis von Pull Requests und Commits über die Zeit</li><li>Kundenorientierte Qualitätsbewertung über die Zeit</li></ul></td></tr><tr><td>Executive</td><td><ul><li>Verhältnis der Anzahl der Releases und Features pro Release</li><li>Kundenorientierte Qualitätsbewertung über die Zeit</li><li>Entwicklungskosten</li></ul></td></tr></tbody></table><p>In der Übersicht taucht mit „<strong>kundenorientierte Qualitätsbewertung</strong>“ eine Metrik auf, die wir bisher nicht betrachtet haben. Die Daten hierfür bekommen wir über Kundenbefragungen bzw. -bewertungen und diese müssen wir dann nur normalisieren. Um die jeweiligen Interessengruppen nicht mit Zahlenkolonnen zu erschlagen, sollten wir uns über die Art die Visualisierung Gedanken machen. Wenn wir uns dem Begriff „Business Intelligence“ wieder zuwenden, stossen wir auf sogenannte Dashboards. Diese sorgen dafür, dass die entstandenen KPIs eine ansprechende Darstellung zur schnellen Verwendbarkeit erhalten.</p><p>Ich hoffe, dass euch dieser Blogpost einen ersten Einblick in die Analyse von Wertströmen innerhalb von Entwicklungsprozessen gegeben hat. In einem nachfolgendem Blogpost werde ich mit Unterstützung der Statistikumgebung <em>R</em> und einiger Bibliotheken eine Umsetzung eines Application Lifecycle Intelligence Dashboard darstellen.</p>

Application Lifecycle Intelligence: Analyse von Wertschöpfung in Entwicklungsprozessen

<p>Seit geraumer Zeit erscheint in Blogposts und auf Konferenzen immer wieder das Thema „API as a Product“. Doch was verbirgt sich konkret dahinter?<br /> Betrachtet man APIs, so steht oftmals die technische Umsetzung im Fokus, wohingegen der Blick auf das Business vernachlässigt wird. Zunehmend werden aber immer mehr Angebote genau in diesem Kontext geschaffen. Wir sollten also dazu übergehen APIs mehr als ein Produkt zu verstehen. Heute benutzen wir diese als Service um einem Nutzer die Möglichkeit zu geben, risiko- und kostenarm auf Core-Ressourcen eines Businesses zugreifen zu können. Diesbezüglich sollten wir eine API auch weniger als reine Codebasis, sondern viel mehr als Teil des Betriebsvermögens ansehen, da wir ja genau mit dieser API entsprechende Betriebswerte generieren.</p><p>Integriert man den betriebswirtschaftlichen Aspekt, so sollte man ein paar Terminologien aus diesem Kontext im Zusammenhang mit APIs näher betrachten.</p><h2>Öffentliche APIs</h2><p>Als ersten Schritt nehmen wir an, dass wir APIs grundsätzlich so entwickeln als wären diese öffentlich zugänglich, also Public APIs. Durch diese Annahme sind wir schon zu Anfang der Entwicklung gezwungen, darauf zu achten, dass die API für jeden potentiellen Konsumenten durch gute Konzeption, Implementierung und Dokumentation einfach zu verstehen und anzuwenden sind.</p><h2>Die Rolle des Konsumenten im API-Umfeld</h2><p>Wir haben es hier mit zwei Arten von Konsumenten zu tun, dem internen und dem externen. Der externe Konsument ist jemand außerhalb des eigentlichen Businesses. Es kann ein konkreter Nutzer oder ein Anbieter eines anderen Services sein. Der interne Konsument ist Teil des Businesses. Für beide Konsumentenarten gilt, dass es sich in der Regel um Entwickler handelt. Aus betriebswirtschaftlicher Sicht steckt hinter jeder Transaktion, ob nach innen oder außen, ein entsprechender Wert. Somit ist die API als Teil der Wertschöpfungskette anzusehen.</p><h2>Entwicklung</h2><p>Nachdem wir uns mit den Konsumenten beschäftigt haben, sollten wir uns der Entwicklung eines API-Produkts zuwenden. Entwicklung ist grundsätzlich ein Prozess, der Kosten verursacht und daher ein Investment darstellt. Diesem Umstand sollte man sich bei der Betrachtung von APIs im Sinne eines Produkts bewusst sein. Bevor es an die konkrete Umsetzung geht, wird ein MVP (Minimal Viable Product) für das API-Produkt definiert. Dazu gehört dann auch eine Roadmap, um zu garantieren, dass die Konsumenten genau das bekommen, was diese wirklich benötigen. Durch diese Limitierung innerhalb der Entwicklung verhindern wir die Umsetzung von nicht benötigten Features, wie z.B. ungenutzten Endpoints. Potentielle Sicherheitslücken werden so reduziert.</p><h2>Unveränderlichkeit</h2><p>Was man bei der Entwicklung einer API auf keinen Fall außer Acht lassen sollte, ist die Unveränderlichkeit eben dieser. Im Sinne des Produktgedanken bedeutet dies, dass entsprechende Änderungen abwärtskompatibel sein müssen, da sonst Investitionen in das Produkt nicht sinnvoll sind.</p><h2>Messbarkeit</h2><p>Nachdem wir nun ein API-Produkt entwickelt haben und dieses den Konsumenten zur Verfügung gestellt wurde, kommt schnell die Frage nach dem Wert des Produkts auf. Hier gilt es nun die Nutzung des Produkts entsprechend zu messen bzw. messbar zu machen. So kann auch einem nicht technischen Publikum der Geschäftswert eines API-Produkts näher gebracht werden. Für dieses Publikum ist aber die Anzahl der APIs innerhalb des Produkts nicht entscheidend.</p><p>Hier einige Fragen für die Entwicklung potentieller Messgrößen:</p><ul><li>Wie lange dauert es, sich für die Benutzung der API zu registrieren?</li><li>Nach welcher Zeit erhält der User den ersten 200er Response von der API?</li><li>Wie oft wurde die API über soziale Netzwerke hinweg geteilt?</li></ul><p>Ein weiterer wichtiger Aspekt der Messbarkeit liegt in der kontinuierlichen Beeinflussbarkeit der Roadmap, dadurch dass wir hier nun über eine direkte Feedback-Schleife zum Konsumenten verfügen.</p><h2>Verfügbarkeit und Bekanntmachung</h2><p>Um ein API-Produkt den Konsumenten verfügbar und bekannt zu machen wird häufig ein Developer Portal verwendet. Über dieses Portal werden die Konsumenten in die Lage versetzt die angebotene API selbstständig kennenzulernen und zu benutzen.</p><h2>Sicherheit</h2><p>Für API-Produkte ist auch Sicherheit ein wichtiger Faktor. Sie sollten daher durch OAuth, API Key Verification, XML/JSON Threat Protection und allgemeine Sicherheitsmechanismen geschützt sein.</p><h2>Fazit</h2><p>Um eine API als Produkt innerhalb der Digitalen Transformation eines Business zu etablieren, müssen wir bei der Umsetzung die genannten Punkte im Blick haben. Das Produkt sorgt schließlich dafür, dass Applikationen und Systeme von überall und zu jeder Zeit miteinander verbunden werden können.<br /> In einem folgendem Blogpost, der im Laufe des Novembers erscheinen wird, wollen wir einen erneuten Blick auf das API-Gateway <a href="https://konghq.com" target="_blank">Kong</a>  werfen, um festzustellen wie uns dieses bei der Umsetzung einer „API as a Product“-Strategie unterstützen kann.</p>

API as a Product

<p>Seit dem letzten <a href="https://blog.codecentric.de/2017/11/api-management-kong/">Blogpost</a>  zu diesem Thema von Alexander Melnyk sind fast zwei Jahre vergangen, und es ist in Sachen „API-Management mit Kong“ eine Menge passiert. Daher war es an der Zeit, zum einen die Inhalte des Posts von Alexander zu aktualisieren und zum anderen das Thema „API-Management mit Kong“ und das Produkt Kong detaillierter zu betrachten. Dieser Post stellt den Beginn einer Serie von Beiträgen dar, welche in nächster Zeit erscheinen werden. Der Schwerpunkt der Serie wird erst einmal auf dem Open-Source-Produkt liegen, d.h. auf dem API-Gateway <a href="https://konghq.com/kong" target="_blank">Kong</a> .</p><h2>Aufbau der Infrastruktur</h2><p>Um euch nicht mit Inhalten aus den Release Notes zu langweilen, wird direkt technisch eingestiegen. Die Grundlage für die folgenden Betrachtungen stellt die Infrastruktur auf Basis eines docker-compose-File dar, welches im <a href="https://github.com/danielkocot/kong-blogposts" target="_blank">GitHub-Repo</a>  zum Artikel gefunden werden kann. Zudem benötigt man ein API. Hierfür wird das Python-Framework <a href="https://fastapi.tiangolo.com" target="_blank">FastAPI</a>  verwendet, welches das API in Form von drei Endpunkten (<code>/</code>(root), <code>service1</code>, <code>service2</code>) in einem Container mittels Dockerfile bereitstellt. Auch das API ist ein Teil des Repos.</p><div>

```python
from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/")
def read_root():
    return {"Hello": "World"}
 
@app.get("/api/service1")
def read_service1():
    return {"status_code": 200, "message": "service1 is called"}
 
@app.get("/api/service2")
def read_service2():
    return {"status_code": 200, "message": "service2 is called"}
```

</div><div>

```bash
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.7
 
COPY ./app /app
```

</div><div>

```bash
version: '3'
networks:
  kong-blogposts:
    driver: bridge
 
services:
  api-service:
    build: ./api-service
    networks:
      - kong-blogposts
    expose:
      - 80
    ports:
      - "80:80"
 
  kong-database:
    container_name: kong-database
    image: postgres:9.6
    restart: always
    networks:
      - kong-blogposts
    environment:
      - POSTGRES_USER=kong
      - POSTGRES_DB=kong
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "kong"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  kong-migration:
    image: kong
    depends_on:
      - "kong-database"
    container_name: kong-migration
    networks:
      - kong-blogposts
    restart: on-failure
    environment:
      - KONG_DATABASE=postgres
      - KONG_PG_HOST=kong-database
      - KONG_PG_DATABASE=kong
    command: kong migrations bootstrap
 
  kong:
    container_name: kong
    image: kong:latest
    depends_on:
      - "kong-migration"
      - "kong-database"
    restart: always
    networks:
      - kong-blogposts
    environment:
      - KONG_DATABASE=postgres
      - KONG_PG_HOST=kong-database
      - KONG_PG_DATABASE=kong
      - KONG_PROXY_LISTEN=0.0.0.0:8000
      - KONG_ADMIN_LISTEN=0.0.0.0:8001
    ports:
      - 8000:8000
      - 8001:8001
      - 8443:8443
      - 8444:8444
    healthcheck:
      test: ["CMD-SHELL","curl -I -s -L http://localhost:8000 || exit 1"]
      interval: 5s
      retries: 10
```

</div><p>Die <code>docker-compose</code>-Definition erzeugt die drei Services <code>kong</code>, <code>kong-database</code> und <code>kong-migration</code>. Als Datenbank bzw. DataStore-Komponente werden wir <a href="https://www.postgresql.org" target="_blank">PostgreSQL</a>  benutzen. Der <code>kong</code>-Service als API-Gateway stellt vier Ports für zwei Endpunkte bereit, zum einen den Consumer- und zum anderen den Admin-Endpunkt, jeweils für http und https.</p><p>Um den <code>kong</code>-Service zu betreiben, wird der <code>kong-migration</code>-Service zur initialen Generierung der Objekte in der <code>kong-database</code> verwendet. Das Befüllen der Datenbank wird leider nicht durch den <code>kong</code>-service erledigt. Die Services werden mit <code>docker-compose up</code> gestartet. Mit dem Befehl <code>docker-compose ps</code> erhalten wir nun eine Übersicht der laufenden Dienste.</p><p><a href="https://media.graphassets.com/9oke7UmrRkGHAsQSxQ2o"><img src="https://media.graphassets.com/9oke7UmrRkGHAsQSxQ2o" alt="Kong: Übersicht über laufende Dienste" width="2816" height="210" /></a> </p><p>Zuerst schaut man, ob Kong erreichbar ist. Hierzu überprüft man den Status des API-Gateways mit einer <code>GET</code>-Anfrage an das Admin-API. Der Aufruf <code>http localhost:8001/status</code> sollte den Statuscode <code>200</code> zurückliefern. Hierzu benutze ich persönlich das Tool <a href="http://httpie.org/" target="_blank">httpie</a> .</p><h2>Von Services, Routen, Consumern und Plugins</h2><p>Man sieht, dass der Zugriff auf das Kong-Admin-API funktioniert, aber bisher noch keine APIs konfiguriert sind. Nun wird ein API hinzugefügt, das aus einem Service und Route besteht. Hier zeigt sich eine Veränderung des Admin API. Ab der Version 0.13 wurden Routen und Services für eine bessere Abgrenzung und die Möglichkeit, Plugins auf bestimmte Endpunkte anzuwenden, eingeführt. Um einen Service anzulegen, sendet man einen POST-Request an das Gateway (<code>localhost:8001/services</code>).</p><p><code>http POST localhost:8001/services/ name=service1 url=http://host.docker.internal/api/service1</code></p><p>Für dieses kurze Einführungsbeispiel werden die anderen möglichen Parameter nicht betrachtet. Da man Kong innerhalb von Docker einsetzt, ist es wichtig die <code>host.docker.internal</code> IP zu verwenden. Sonst kommt es zu Schwierigkeiten beim Aufruf des API über das API-Gateway.</p><p>Nachdem der Service angelegt wurde, muss außerdem noch eine Route erstellt werden.</p><p><code>http POST localhost:8001/services/service1/routes paths:='["/service1"]' name=service1_route methods:='["GET"]'</code></p><p>Über <code>http localhost:8000/service1</code> lässt sich der Service aufrufen und liefert das folgende Ergebnis zurück.</p><div>

```bash
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 50
Content-Type: application/json
Via: kong/1.3.0
X-Kong-Proxy-Latency: 7
X-Kong-Upstream-Latency: 5
server: uvicorn
 
{
   "message": "service1 is called",
   "status_code": 200
}
```

</div><p>Im Regelfall möchte man ja sein API vor unberechtigten Zugriffen schützen bzw. nur dezidierten Usern Zugriff gewähren. In Kong verwendet man hierfür Plugins, die während eines Requests ausgeführt werden. Um entsprechende technische User zur Verfügung zu stellen, bietet Kong eine weitere Entität an: die Consumer.</p><p><code>http post localhost:8001/consumers username=api-user</code></p><div>

```bash
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 120
Content-Type: application/json; charset=utf-8
Date: Sun, 01 Sep 2019 10:02:54 GMT
Server: kong/1.3.0
 
{
    "created_at": 1567332174,
    "custom_id": null,
    "id": "a37333ea-c346-488b-a1f0-1a0b078ea152",
    "tags": null,
    "username": "api-user"
}
```

</div><p>Man fügt dem API das Key Authentication Plugin hinzu und verbindet ebenfalls den Consumer damit. Dadurch wird sichergestellt, dass eben nur dieser Consumer mit einem bestimmten Schlüssel auf das API zugreifen kann.</p><p><code>http post localhost:8001/services/service1/plugins name=key-auth</code></p><div>

```bash
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 380
Content-Type: application/json; charset=utf-8
Server: kong/1.3.0
 
{
    "config": {
        "anonymous": null,
        "hide_credentials": false,
        "key_in_body": false,
        "key_names": [
            "apikey"
        ],
        "run_on_preflight": true
    },
    "consumer": null,
    "created_at": 1567332763,
    "enabled": true,
    "id": "a3b0ea80-98ba-43ed-a3dd-9fb5e1b0bbad",
    "name": "key-auth",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ],
    "route": null,
    "run_on": "first",
    "service": {
        "id": "3d0d837d-8d42-4764-9111-16f195baf762"
    },
    "tags": null
}
```

</div><p>Es folgt die Überprüfung, ob das Plugin eingerichtet ist.</p><p><code>http localhost:8000/service1</code></p><div>

```bash
HTTP/1.1 401 Unauthorized
Connection: keep-alive
Content-Length: 41
Content-Type: application/json; charset=utf-8
Server: kong/1.3.0
WWW-Authenticate: Key realm="kong"
 
{
    "message": "No API key found in request"
}
```

</div><p>Nun muss noch ein Schlüssel für den Consumer <code>api-user</code> erstellt werden. Falls kein key angegeben ist, wird dieser automatisch erstellt.</p><p><code>http post localhost:8001/consumers/api-user/key-auth key=secret_key</code></p><div>

```bash
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 145
Content-Type: application/json; charset=utf-8
Server: kong/1.3.0
 
{
    "consumer": {
        "id": "a37333ea-c346-488b-a1f0-1a0b078ea152"
    },
    "created_at": 1567333309,
    "id": "e65bcc7a-9478-40cc-be6c-0df43bad5b03",
    "key": "secret_key"
}
```

</div><p>Der Aufruf des API erfolgt mit dem <code>api-key</code> und liefert das folgende Ergebnis zurück.</p><p><code>http localhost:8000/service1 apikey:secret_key</code></p><div>

```bash
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 50
Content-Type: application/json
Via: kong/1.3.0
X-Kong-Proxy-Latency: 8
X-Kong-Upstream-Latency: 35
date: Sun, 01 Sep 2019 10:27:25 GMT
server: uvicorn
 
{
    "message": "service1 is called",
    "status_code": 200
}
```

</div><p>Alle gezeigten Schritte lassen sich jetzt auch auf den zweiten Service (<code>service2</code>) anwenden. Wenn dies vollzogen ist, sind beide Services durch Kong abgesichert.</p><h2>Ausblick</h2><p>Schließlich haben wir auch das Ende des ersten Teils der Serie zu Kong erreicht. Ich hoffe, dass Euch dieser erste Post einen Einblick in die Funktionsweise und erste Änderung des Kong-Admin-API gegeben hat. In den folgenden Teilen werde ich neben Kong auch auf <a href="https://konghq.com/kong-enterprise" target="_blank">Kong Enterprise</a> , die Service Control Platform, eingehen. Seid also gespannt!</p>

API-Management mit Kong – Ein Update und mehr

<p>Seit dem letzten <a href="/wissens-hub/blog/api-management-kong-update" target="_blank">Post</a>  ist eine neue Version (<a href="https://github.com/Kong/kong/blob/master/CHANGELOG.md#140" target="_blank">1.4</a> ) des Kong API Gateways veröffentlicht worden. Die größte Neuerung stellt die <em>/status</em>-Route dar. Über diese lässt sich der Status eines Gateways direkt abfragen. Anfang Dezember ist auch ein Patch-Release (<a href="https://github.com/Kong/kong/blob/master/CHANGELOG.md#141" target="_blank">1.4.1</a> ) erschienen.</p><p>Nachdem nun die ersten zwei Services manuell angelegt wurden, ist es an der Zeit, über erste Möglichkeiten einer Automatisierung nachzudenken. Da der Design- und Entwicklungsprozess von APIs auf Basis kontinuierlicher Softwareentwicklungsprozessen stattfinden sollte, benötigen wir eine Möglichkeit, die Erstellung von Services, Routen und die Verknüpfung von Plug-ins in bestehende CI/CD-Prozesse einzubauen. Hier kann decK eine große Hilfe sein. Das Tool decK wurde von <a href="https://github.com/hbagdi" target="_blank">Harry Bagdi</a>  entwickelt. Harry arbeitet als Senior Cloud Engineer bei Kong.</p><h2>decK</h2><p><a href="https://github.com/hbagdi/deck#installation" target="_blank">decK</a>  versetzt uns in die Lage, deklarative Konfigurationen in Form einer YAML-Datei für Kong zu erstellen und somit auch erweiterte Möglichkeiten der Pflege der Konfiguration des Kong API Gateways zu gewährleisten. Das wichtigste Feature ist hierbei <em>reverse-sync</em> , das decK in die Lage versetzt, aktuelle Entitäten in der Kong-Datenbank zu entdecken, die nicht noch Teil der Konfigurationsdatei sind.</p><p>Zu allererst möchte ich nun aus dem API Gateway die Konfiguration auslesen. Dies geschieht über einen Dump.</p>

```code-highlighted code-bash
deck dump
```

<p>Durch Ausführen des Befehls wird die gesamte Konfiguration aus der Datenbank heraus in eine YAML-Datei geschrieben.</p>

```code-highlighted code-bash
_format_version: "1.1"
services:
- connect_timeout: 60000
  host: host.docker.internal
  name: service1
  path: /api/service1
  port: 80
  protocol: http
  read_timeout: 60000
  retries: 5
  write_timeout: 60000
  routes:
  - name: service1_route
    methods:
    - GET
    paths:
    - /service1
    preserve_host: false
    protocols:
    - http
    - https
    regex_priority: 0
    strip_path: true
    https_redirect_status_code: 426
  plugins:
  - name: key-auth
    config:
      anonymous: null
      hide_credentials: false
      key_in_body: false
      key_names:
      - apikey
      run_on_preflight: true
    enabled: true
    run_on: first
    protocols:
    - grpc
    - grpcs
    - http
    - https
- connect_timeout: 60000
  host: host.docker.internal
  name: service2
  path: /api/service2
  port: 80
  protocol: http
  read_timeout: 60000
  retries: 5
  write_timeout: 60000
  routes:
  - name: service2_route
    methods:
    - GET
    paths:
    - /service2
    preserve_host: false
    protocols:
    - http
    - https
    regex_priority: 0
    strip_path: true
    https_redirect_status_code: 426
  plugins:
  - name: key-auth
    config:
      anonymous: null
      hide_credentials: false
      key_in_body: false
      key_names:
      - apikey
      run_on_preflight: true
    enabled: true
    run_on: first
    protocols:
    - grpc
    - grpcs
    - http
    - https
consumers:
- username: api-user
  keyauth_credentials:
  - key: secret_key
```

<p>Wenn ich nun die Route <em>/service1 </em>mittels <code>http POST :8001/services/service1/plugins name=proxy-cache config.strategy=memory -f </code> mit dem Proxy-Cache-Plug-in belege, ist es im Anschluss möglich, mit <code>deck diff</code> die gesicherte Konfiguration mit den aktuellen Einträgen in der Kong-Datenbank zu vergleichen. Nun kommt die sogenannte <em>drift detection</em> zum Tragen, da das Cache-Plug-in in der YAML-Datei nicht existiert.</p>

```code-highlighted code-bash
deleting plugin proxy-cache for service d9a029b8-5e5c-4f33-8131-a77197903275
Summary:
  Created: 0
  Updated: 0
  Deleted: 1
```

<p>Wenn ich nun im Anschluss einen Sync ausführe, wird das Plug-in aus der Datenbank gelöscht.</p><p>Dies zeigt, dass decK Änderungen durch Kongs Admin-API sehr einfach erkennen kann . Dies lässt sich nun in die CI-Pipeline entsprechend einbauen, um mittels eines Cronjobs auf Veränderungen in der Konfigurationsdatei reagieren zu können.</p><h2>Konga</h2><p>Grundsätzlich habe ich bisher das Kong Gateway nur über die Admin API bedient. Dies kann gerade in einem Team nicht wirklich zu einer besseren Transparenz hinsichtlich des API Gateways beitragen. Wir Menschen lieben ganz klar das Visuelle. Und deswegen finden wir auch immer wieder Gefallen an Dashboards. Für den Duden ist ein Dashboard: „<em>Computerprogramm, das relevante Informationen zusammenfasst und übersichtlich darstellt</em>“ (<a href="https://www.duden.de/rechtschreibung/Dashboard">https://www.duden.de/rechtschreibung/Dashboard</a> ). Genau ein solches Dashboard ist aber nicht Bestandteil des Kong API Gateways als Open-Source-Produkt. Deswegen entwickelte <a href="http://www.linkedin.com/in/tselentis-panagis" target="_blank">Panagis Tselentis</a> , Software Engineer bei ING, <a href="https://github.com/pantsel/konga" target="_blank">Konga</a> . Konga ist auch ein Open-Source-Produkt und versetzt uns in die Lage, alle Kong Admin-API-Objekte in einer grafischen Oberfläche zu verwalten.</p><p>Damit Konga ein Teil der vorhandenen Demo wird, erweitere ich unsere vorhandene docker-compose-Datei um die folgenden Zeilen:</p>

```code-highlighted code-bash
konga-prepare:
    image: pantsel/konga:next
    container_name: konga-prepare
    command: "-c prepare -a postgres -u postgresql://kong@kong-database:5432/konga_db"
    networks:
      - kong-blogposts
    restart: on-failure
    depends_on: 
      - kong-database

  konga:
    image: pantsel/konga:latest
    container_name: konga
    restart: always
    networks:
      - kong-blogposts
    environment:
      - DB_ADAPTER=postgres
      - DB_HOST=kong-database
      - DB_USER=kong
      - TOKEN_SECRET=km1GUr4RkcQD7DewhJPNXrCuZwcKmqjb
      - DB_DATABASE=konga_db
      - NODE_ENV=production
      - NO_AUTH=true
    depends_on:
      - kong-database
      - konga-prepare
    ports:
      - "1337:1337"
```

<p>Da Konga auch eine Datenbank benötigt, habe ich auch wieder einen Container für die Einrichtung der Datenbank (<em>konga-prepare</em>) erstellt. Die Applikation wird mittels <em>http://localhost:1337</em> aufgerufen.</p><p>Nun muss noch eine Verbindung zum Kong API Gateway hergestellt werden.</p><figure><a href="https://media.graphassets.com/JrHeyPBT5KfCBnTYb3i1"><img width="150" height="150" src="https://media.graphassets.com/JrHeyPBT5KfCBnTYb3i1" alt="kong api gateway" /></a> </figure><p>Im Anschluss erhalte ich erste Informationen zu meinem Gateway in sehr einfacher Form.</p><figure><a href="https://media.graphassets.com/7tIeYCbGTfy9Aje2tUWW"><img loading="lazy" width="250" height="138" src="https://media.graphassets.com/7tIeYCbGTfy9Aje2tUWW" alt="kong api gateway" /></a> </figure><p>Da ich das Hauptaugenmerk auf die Automatisierung des Kong API Gateways innerhalb von CI/CD-Prozessen legen möchte, soll dieser kurze Blick auf Konga reichen. Die Anpassungen findet ihr auch im Repo bei <a href="https://github.com/danielkocot/kong-blogposts" target="_blank">Github</a> .</p>

Kong API Gateway – Deklarative Konfiguration mit decK und Visualisierung mit Konga

<p>Im vorherigen <a href="https://blog.codecentric.de/2019/12/kong-api-gateway-deklarative-konfiguration-mit-deck-und-visualisierung-mit-konga/" target="_blank">Blogpost</a>  habe ich das bestehende Demo-Setup um decK und Konga erweitert. Nun soll es darum gehen, die vorhandenen Daten der APIs sichtbarer werden zu lassen. Hierzu möchte ich zwei Observability Patterns, nämlich Monitoring und Alerting, in Verbindung mit einem API-Gateway, im Speziellen Kong, betrachten. Doch was bedeutet eigentlich Observability?</p><h2>Observability</h2><p>Der Begriff <em>Observability</em> stammt ursprünglich aus der mathematischen Kontrolltheorie und ist eine Messgröße, die Rückschlüsse auf den inneren Zustand eines Systems zulassen soll. Geprägt wurde dieser Begriff von Robert E. Kalman. Dies kann auch auf Applikationen als Systeme übertragen werden. Im Folgenden wird das API-Gateway die Rolle eines zu beobachteten Systems einnehmen. Um nun die entsprechenden Patterns anwenden zu können, werde ich auf die darauffolgenden Tools zurückgreifen und diese jeweils kurz erläutern.</p><h2>Monitoring</h2><p>Beim Monitoring befassen wir uns mit der Überwachung von Metriken, was in unserem Fall die Güte einer Verbindung bei Verwendung einer bestimmten Route meint. Diese Metriken erfassen wir mittels Prometheus und eines entsprechenden Kong-Plug-ins (<a href="https://docs.konghq.com/hub/kong-inc/prometheus/">https://docs.konghq.com/hub/kong-inc/prometheus/</a> ). Das Plug-in wird am Service mithilfe von decK eingerichtet. Dazu wird unter <em>plugins</em>: die YAML-Datei um folgende Einträge erweitert.</p>

```code-highlighted code-bash
- name: prometheus
    enabled: true
    run_on: first
    protocols:
    - grpc
    - grpcs
    - http
    - https
```

<h3>Prometheus</h3><p>Um <a href="http://www.prometheus.io" target="_blank">Prometheus</a>  starten zu können, muss es noch zur <em>docker-compose</em>-Datei hinzugefügt werden.</p>

```code-highlighted code-bash
prometheus:
    image: prom/prometheus
    container_name: prometheus
    restart: always
    volumes: 
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command: "--config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/prometheus"
    ports: 
      - 9090:9090
```

<p>Es muss eine Konfiguration mittels prometheus.yml erstellt werden.</p>

```code-highlighted code-bash
global:
  scrape_interval:      15s
  evaluation_interval:  15s

scrape_configs:
  - job_name: 'prometheus' 
    metrics_path: /metrics
    honor_labels: false
    honor_timestamps: true
    sample_limit: 0
    static_configs:
      - targets: ['localhost:9090','host.docker.internal:8001']
```

<p>Nach dem Aufruf von „docker-compose up“ startet Prometheus und steht unter <em>http://localhost:9090</em> zur Verfügung. Da die Oberfläche sehr spartanisch ist und sich hauptsächlich für schnelle Abfragen und Debugging eignet, kommt ein weiteres Tool ins Spiel, Grafana.</p><p><em>Tipp: Wenn du dich mehr mit API Management beschäftigen oder das Thema deinem Team näher bringen möchtest, lohnt sich ein Blick auf unser kostenloses Event-Angebot „Brown Paper Bag Lunch“. Unsere Experten besuchen euch inhouse, bringen Lunch mit und erklären das Thema en detail. Es gibt auch verschiedene Menüs, aus denen du auswählen kannst: <a href="https://info.codecentric.de/api-management-lunch" target="_blank">https://info.codecentric.de/api-management-lunch</a> </em></p><h3>Grafana</h3><p>Wie Prometheus ist auch <a href="https://grafana.com" target="_blank">Grafana</a>  ein Open-Source Produkt. Grafana versetzt den User in die Lage, Dashboards für das Monitoring von Systemen zu erstellen.</p><p>Hierzu füge ich Grafana ebenfalls zur vorhandenen <em>docker-compose</em>-Datei hinzu.</p>

```code-highlighted code-bash
grafana:
    image: grafana/grafana
    container_name: grafana
    restart: always
    volumes: 
      - ./grafana/provisioning/:/etc/grafana/provisioning
    ports:
      - 3000:3000
```

<p>Im Unterordner <em>grafana/provisioning</em>befinden sich die Konfiguration für die möglichen vorgefertigten Dashboards und Datasources. Für Kong greife ich auf das offizielle Grafana Dashboard von Kong zurück. Dieses ist auch im Unterordner hinterlegt.</p><p>Mit <em>docker-compose up</em>starte ich Grafana und es steht unter <em>http://localhost:3000</em> im Anschluss zur Verfügung. Nach der Anmeldung mittels <em>admin:admin</em>ist der Aufruf des Dashboards „Kong (official)“ möglich.</p><h2>Alerting</h2><p>Zu diesem Zeitpunkt ist eine Monitoring-Lösung für das API-Gateway integriert. Was noch fehlt, sind Hinweise und Warnungen, wenn das Gateway vorher vereinbarte Schwellenwerte erreicht. Genau damit eröffnet sich der Weg in Richtung Alerting. Für die Beispielarchitektur gilt es nun ein entsprechendes Alerting auf Basis von Grafana herzustellen. Dies könnte auch über Prometheus erfolgen, hierzu müsste ein weiterer Container zur Multi-Container-Umgebung hinzugefügt werden.</p><p>Als erstes werde ich nun einen Notification Channel angelegen, und zwar konkret für OpsGenie. Auf dem Bild sind noch viele weitere Kanäle erkennbar. Für die Integration mit OpsGenie wird ein API-Key und eine URL benötigt.</p><figure><a href="https://media.graphassets.com/nxHxKUpQlmkLlzk325WS"><img width="250" height="260" src="https://media.graphassets.com/nxHxKUpQlmkLlzk325WS" alt="Oberservability: Alert Notification" /></a> </figure><p>Des Weiteren lege ich noch ein neues Dashboard mit einem neuen Panel an. Als Metrik sollen alle HTTP Status Code vom Typ <em>401</em> erfasst werden. Als Alert lege ich einen Schwellenwert fest, der im Beispiel entweder dem Typ <em>max()</em> oder <em>avg()</em> zuzuordnen ist. Zum Schluss muss nur noch der entsprechende Notification Channel ausgewählt werden. Ebenso können zusätzliche Nachrichten oder Tags hinterlegt werden. Somit ist die Konfiguration seitens Grafana abgeschlossen.</p><figure><a href="https://media.graphassets.com/b1zHnyxOTqKP8wCeRjvF"><img loading="lazy" width="250" height="107" src="https://media.graphassets.com/b1zHnyxOTqKP8wCeRjvF" alt="Grafana Dashboard" /></a> </figure><h3>OpsGenie</h3><p><a href="https://www.atlassian.com/software/opsgenie" target="_blank">OpsGenie</a>  stellt das zweite Tool innerhalb des Alerting-Prozesses dar. Grafana ist zwar in der Lage entsprechende Alerts auszulösen, aber eine wirkliche Benachrichtigung mit einem Hinweis ist in Grafana nicht direkt vorgesehen. Hier kommt OpsGenie ins Spiel. OpsGenie ist eine Incident Management Platform, die auf Basis von Alerts arbeitet. Aufgrund der bidirektionalen Integrationsansatzes und der Vielzahl von Integrationen lässt sie sich theoretisch in jede Architektur integrieren.</p><p>Die Integrationen werden immer pro Team vorgenommen.</p><figure><a href="https://media.graphassets.com/Q7BFxO8mT4KpoS3yOGEn"><img loading="lazy" width="250" height="95" src="https://media.graphassets.com/Q7BFxO8mT4KpoS3yOGEn" alt="OpsGenie Integrations" /></a> </figure><p>Wie auf dem Bild zu erkennen, ist eine Integration für Grafana schon eingerichtet. Hier findet man auch den API-Key und die URL. Nun sind die beiden Tools miteinander verbunden. Entsprechend der Einstellungen von OpsGenie werden die Alerts von Grafana nun als Sprachnachricht, SMS oder E-Mail an die entsprechenden Personen des Teams weitergeleitet.</p><p>Somit ist ein guter erster Schritt in Richtung Observability für das Kong API-Gateway getan.Die Erweiterungen findet ihr im Repo bei <a href="https://github.com/danielkocot/kong-blogposts" target="_blank">GitHub</a>  unter dem Branch <em>observe</em>.</p>

Kong API-Gateway – Observability mit Prometheus, Grafana und OpsGenie

<p>Die bisherigen <a href="https://blog.codecentric.de/tag/kong-2/" target="_blank">Blogposts</a>  zu Kong aus dem vergangenen Jahr haben sich dem API Gateway beschäftigt, welches als Open-Source-Produkt zur Verfügung gestellt wird. Seit Ende September / Anfang Oktober 2019 ist codecentric Go-To-Market-Partner in EMEA, vor allem aber in der DACH-Region. Als Go-To-Market-Partner beschäftigen wir uns auch mit Kong Enterprise, einer Plattform, die der Unterstützung des gesamten Lebenszyklus von APIs und Services dient.</p><p>Das Produkt besteht aus mehreren Komponenten, denen ich mich in einer neuen Blogpost-Serie nun widmen möchte. Die erste Komponente ist uns schon aus den bisherigen Blogposts bekannt: das Gateway. Es wird aktuell (Ende Mai 2020) bei Kong Enterprise mit der Versionsnummer 1.5 ausgeliefert. Hier zeigt sich ein großer Unterschied zum Open-Source-Produkt, welches schon seit März 2020 in der Version 2.0 verfügbar ist, und zeigt zugleich, wie wichtig Kong als Hersteller das Enterprise-Produkt ist, da neue Features des Open-Source-Produktes erst eine gewisse Reife erhalten, bevor diese dann ein Teil des Enterprise-Produktes werden. Die folgende Grafik stellt die einzelnen Komponenten schematisch dar.</p><figure><a href="https://media.graphassets.com/hZd7z53SHGiP6pRlftkZ"><img width="250" height="125" src="https://media.graphassets.com/hZd7z53SHGiP6pRlftkZ" alt /></a> <figcaption>(c) Kong Inc</figcaption></figure><p>Im Gegensatz zum Kong Gateway als Open-Source-Produkt fällt zu allererst die Möglichkeit der rollenbasierte Zugriffskontrolle (RBAC) für die Administration des Gateways auf. Obwohl sich die Teams einer Organisation denselben Kong-Cluster teilen können, ist es möglich, den Cluster in logische Gruppen mit beschränktem Zugang zu unterteilen. Diese Workspaces ermöglichen eine klarere Segmentierung des Traffics und der Entitäten. Der Zugriff jedes Teams kann auf seinen eigenen Workspace beschränkt werden, wodurch das Prinzip der geringsten Privilegien unterstützt wird.</p><p>Neben den Open-Source-Plugins bietet Kong Enterprise auch „Enterprise Plugins“ an. Diese werden in zukünftigen Blogposts durch entsprechende Use Cases vorgestellt.</p><p>Die Komponente „Kong Manager“ bildet das grafische User Interface der Plattform ab. Hier lassen sich dann auch durch Kong Vitals verschiedene Metriken grafisch direkt betrachten.</p><p>Zu guter Letzt ist auch ein Developer-Portal Teil des Funktionsumfangs von Kong Enterprise. Durch das Portal erhalten Entwickler die Möglichkeit, Services zu finden, auf diese zuzugreifen und auch zu nutzen.</p><p>Die beiden Module „Brain“ und „Immunity“ sind noch separat zu betrachten, da sie nicht direkt Teil von Kong Enterprise sind. Mit Brain lässt sich die Erstellung der API- und Service-Dokumentation automatisieren. Unterstützt durch Machine Learning hilft Immunity bei der Analyse von Traffic Pattern, um die Sicherheit des Gateway zu erhöhen.</p><h2>Aufsetzen einer sicheren Entwicklungsumgebung</h2><p>Nach Betrachtung einiger Komponenten von Kong Enterprise, möchte ich nun zeigen, wie man sich eine sichere lokale Umgebung erstellen kann. Durch Automatisierung lässt sich die Konfiguration auch später in eine produktive Umgebung übertragen.</p><p>Die Basis unserer lokalen Umgebungen stellt, wie schon vorher bei den Posts zu Kong Gateway, eine docker-compose-Datei dar.</p>

```
version: "3"
networks: 
  kong-ent-net:
    driver: bridge

services: 

  api-service:
    build: ./api-service
    ports: 
      - 80:80

  kong-database:
    image: postgres:9.6
    restart: always
    networks: 
    - kong-ent-net
    container_name: kong-database
    environment:
    - POSTGRES_USER=kong
    - POSTGRES_PASSWORD=kong
    - POSTGRES_DB=kong
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  kong-migration:
    image: kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition
    command: kong migrations bootstrap
    networks: 
      - kong-ent-net
    container_name: kong-migration
    restart: on-failure
    environment: 
    - KONG_PG_HOST=kong-database
    - KONG_PG_PASSWORD=kong
    - KONG_DATABASE=postgres
    - KONG_PG_DATABASE=kong
    - 'KONG_LICENSE_DATA=${KONG_LICENSE_DATA}'
    - KONG_PASSWORD=${KONG_PASSWORD}
    links:
      - kong-database
    depends_on: 
      - kong-database
  
  kong-ent:
    image: kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition
    container_name: kong-ent
    depends_on:
      - kong-migration
      - kong-database
    restart: always
    networks:
      - kong-ent-net
    ports:
    - 8000:8000
    - 8001:8001
    - 8002:8002
    - 8003:8003 
    - 8004:8004
    - 8443:8443
    - 8444:8444
    - 8445:8445
    - 8446:8446
    - 8447:8447
    environment:
    - KONG_ENFORCE_RBAC=on
    - KONG_ADMIN_GUI_AUTH=basic-auth
    - KONG_ADMIN_GUI_SESSION_CONF=${KONG_ADMIN_GUI_SESSION_CONF}
    - KONG_AUDIT_LOG=on
    - KONG_LOG_LEVEL=debug
    - KONG_PORTAL_GUI_HOST=localhost:8003
    - KONG_PORTAL_GUI_PROTOCOL=http
    - KONG_PORTAL=on
    - KONG_PORTAL_AUTH=basic-auth
    - KONG_PORTAL_SESSION_CONF=${KONG_PORTAL_SESSION_CONF}
    - KONG_ADMIN_GUI_URL=http://localhost:8002
    - KONG_DATABASE=postgres
    - KONG_PG_PASSWORD=kong
    - KONG_PG_HOST=kong-database
    - KONG_PG_DATABASE=kong
    - 'KONG_LICENSE_DATA=${KONG_LICENSE_DATA}'
    - KONG_VITALS=on
    - KONG_ANONYMOUS_REPORTS=off
    - KONG_PROXY_ACCESS_LOG=/dev/stdout
    - KONG_ADMIN_ACCESS_LOG=/dev/stdout
    - KONG_PROXY_ERROR_LOG=/dev/stderr
    - KONG_ADMIN_ERROR_LOG=/dev/stderr
    - KONG_PROXY_LISTEN=0.0.0.1:8000, 0.0.0.1:8443 ssl
    - KONG_ADMIN_LISTEN=0.0.0.1:8001, 0.0.0.1:8444 ssl
    - KONG_ADMIN_GUI_LISTEN=0.0.0.0:8002, 0.0.0.0:8445 ssl
    - KONG_PORTAL_GUI_LISTEN=0.0.0.0:8003, 0.0.0.0:8446 ssl
    - KONG_PORTAL_API_LISTEN=0.0.0.0:8004, 0.0.0.0:8447 ssl
    healthcheck:
      test: ["CMD-SHELL","kong","health"]
      interval: 5s
      retries: 10
```

<p>Das entsprechende Docker-Image von Kong Enterprise erhält man über einen kundenspezifischen Bintray-Zugang. Zusätzlich wird noch ein Lizenzschlüssel benötigt. Dieser muss nur in einer .env-Datei hinterlegt werden.</p>

```
KONG_PASSWORD=CodeCentric2020!

KONG_ADMIN_GUI_SESSION_CONF={"secret":"secret","storage":"kong","cookie_secure":false}

KONG_PORTAL_SESSION_CONF={"cookie_name":"$cc2020k","secret":"super-secret","storage":"kong","cookie_secure":false}

KONG_LICENSE_DATA={}
```

<p>Durch die Verwendung von <code>KONG_PASSWORD</code> wird der eingebaute Super Admin Account aktiviert, der unter anderem dafür sorgt, dass jeder Aufruf des Rest Admin API zusätzlich den Kong-Admin-Token als Parameter benötigt. Auf diese relativ einfache Art und Weise haben wir auch schon unsere Entwicklungsumgebung abgesichert. Und dies bildet nun auch den Ausgangspunkt für die folgenden Blogposts.</p><p>Weitere Informationen zu unserer Partnerschaft mit Kong sind <a href="https://www.codecentric.de/partner/kong/">hier</a>  zusammengefasst.</p>

Kong Enterprise – Die Service Control Platform

<p>Nach fast fünf Jahren bei codecentric ist es nun endlich so weit, dass ich auf meine Zeit vor codecentric zurückblicke und ein Thema betrachten möchte, das immer noch viele Menschen im Rahmen von Softwareentwicklungsprojekten bewegt: die Generierung von PDFs. Noch immer versuchen wir, mithilfe von Bibliotheken wie iText oder PDFBox auf programmatische Weise diese portablen Dokumente zu erzeugen. Was mit einfachen Layouts auch einwandfrei funktioniert. Aber was passiert, wenn die Layouts und Datenlagen komplexer erscheinen und die Geschwindigkeit bei der Erstellung entscheidend ist?</p><p>Dazu möchte ich ein wenig in der Zeit zurückgehen. Während meines Studiums Anfang der 2000er und auch danach habe ich immer wieder versucht, die Erstellung von PDFs auf Basis von <a href="https://www.latex-project.org" target="_blank">LaTeX</a>  und einiger Derivate wie <a href="http://luatex.org" target="_blank">Lua(La)TeX</a>  und <a href="https://wiki.contextgarden.net/Main_Page" target="_blank">ConTeXt</a>  zu automatisieren, wobei die Datenlagen grundsätzlich unterschiedlich waren. Und genau diese erfolgreichen Experimente führten dazu, dass ich mich Anfang der 2010er in die Welt des Consulting und der Entwicklung begab und in einem Team versuchte, einen TeX-Renderer in den Markt des Database Publishings zu bringen. Hierbei ging es konkret darum, Kataloge und Datenblätter in hoher Stückzahl und gleichzeitig hoher Geschwindigkeit zu erstellen. Es ergaben sich eine Menge Projekte mit vielen Learnings und vielen interessanten Einblicken in komplexe Datenstrukturen sowie entsprechenden Datenbanken und ersten Schritten hin zu Integrationen. Mitte der 2010er wurde ich dann auf ein Produkt aufmerksam, das zumindest den Aufwand hinsichtlich der Erstellung von Layouts zu reduzieren versprach: <a href="https://www.speedata.de/de/" target="_blank">speedata Publisher</a> . Bei diesem Renderer bilden XML-Dateien die Grundlage sowohl bezogen auf die Daten als auch auf ein mögliches Layout. Das Tool basiert ansonsten technologisch auf LuaTeX, Lua und Go. Nun aber genug der Theorie und Geschichte, hinein in die Praxis.</p><h2>Installation und sonstige Voraussetzungen</h2><p>Zuallererst wollen wir den Publisher auf unserem jeweiligen System installieren. Hierzu werden für das jeweilige Betriebssystem Pakete zur Verfügung gestellt. Für die nachfolgenden Betrachtungen verwende ich den Development-Release (bei Veröffentlichung des Blog-Posts in der Version <a href="https://download.speedata.de" target="_blank">4.3.7</a> ), Visual Code Studio mit XML-Extension von Red Hat. Der speedata Publisher wird mit <code>sp</code> im Terminal aufgerufen, dazu muss in der Path-Variable das <code>bin</code>-Verzeichnis des Publishers hinterlegt werden. Um die Autovervollständigung in Visual Studio Code nutzen zu können, hinterlegen wir in den Einstellungen der XML-Extension das XML-Schema des Publishers.</p><h2>Das obligatorische Beispiel</h2><p>Beim Database Publishing geht es ja, wie der Begriff schon erkennen lässt, um die Veröffentlichung von Daten aus einer entsprechenden Quelle. Für den speedata Publisher müssen die Daten in Form einer XML bereitstehen. Wobei das Produkt auch in der Lage ist, entsprechende Datenlage mit vorgelagerten Filtern in XML umzuwandeln. Dies würde diesen Einführungspost inhaltlich deutlich sprengen. Für das Beispiel verwenden wir Produktdaten eines fiktiven Baumarktes, die sich in Zeiten von Corona großer Beliebtheit erfreuen.</p>

```code-highlighted code-xml
<products>
    <product name="Schnellbauschraube">
        <image>screw.pdf</image>
        <description>
            <diameter>3,9mm</diameter>
            <details>Senkkopf, Grobgewinde</details>
            <dash>Ideal für Gipskartonplatten auf Holz</dash>
            <dash>Phosphatierte Oberfläche</dash>
            <dash>Gute Anhaftung von Gips auf dem Schraubkopf</dash>
            <dash>Vor Rost geschützt</dash>
        </description>
        <attribute type="length" value="25mm">
            <quantity unit="Stk" price="2" currency="€">200</quantity>
            <quantity unit="Stk" price="5" currency="€">500</quantity>
            <quantity unit="Stk" price="7" currency="€">1000</quantity>
        </attribute>
        <attribute type="length" value="35mm">
            <quantity unit="Stk" price="3" currency="€">200</quantity>
            <quantity unit="Stk" price="6" currency="€">500</quantity>
            <quantity unit="Stk" price="8" currency="€">1000</quantity>
        </attribute>
        <attribute type="length" value="45mm">
            <quantity unit="Stk" price="4" currency="€">200</quantity>
            <quantity unit="Stk" price="7" currency="€">500</quantity>
            <quantity unit="Stk" price="9" currency="€">1000</quantity>
        </attribute>
    </product>
    <product name="Schraubendreher-Set">
        <image>screwdrivers.pdf</image>
        <description>
            <details>Geeignet für: Schlitz und Kreuzschlitz PH, 6-tlg.</details>
            <dash>Isolierte VDE Klingen für sicheres Arbeiten</dash>
            <dash>Mehrkomponentiger Griff</dash>
            <dash>Mit Griffkennzeichnung zum leichteren Finden</dash>
            <dash>Erhöhter Korrosionsschutz</dash>
        </description>
        <attribute type="package" value="6">
            <quantity unit="Verpackung" price="11" currency="€">1</quantity>
        </attribute>
    </product>
    <product name="Schraubendreher-Set">
        <image>screwdrivers.pdf</image>
        <description>
            <details>Geeignet für: Schlitz und Kreuzschlitz PH, 6-tlg.</details>
            <dash>Isolierte VDE Klingen für sicheres Arbeiten</dash>
            <dash>Mehrkomponentiger Griff</dash>
            <dash>Mit Griffkennzeichnung zum leichteren Finden</dash>
            <dash>Erhöhter Korrosionsschutz</dash>
        </description>
        <attribute type="package" value="6">
            <quantity unit="Verpackung" price="11" currency="€">1</quantity>
        </attribute>
    </product>
    <product name="Schraubendreher-Set">
        <image>screwdrivers.pdf</image>
        <description>
            <details>Geeignet für: Schlitz und Kreuzschlitz PH, 8-tlg.</details>
            <dash>Isolierte VDE Klingen für sicheres Arbeiten</dash>
            <dash>Mehrkomponentiger Griff</dash>
            <dash>Mit Griffkennzeichnung zum leichteren Finden</dash>
            <dash>Erhöhter Korrosionsschutz</dash>
        </description>
        <attribute type="package" value="8">
            <quantity unit="Verpackung" price="13" currency="€">1</quantity>
        </attribute>
    </product>
    <product name="Schraubendreher-Set">
        <image>screwdrivers.pdf</image>
        <description>
            <details>Geeignet für: Schlitz und Kreuzschlitz PH, 10-tlg.</details>
            <dash>Isolierte VDE Klingen für sicheres Arbeiten</dash>
            <dash>Mehrkomponentiger Griff</dash>
            <dash>Mit Griffkennzeichnung zum leichteren Finden</dash>
            <dash>Erhöhter Korrosionsschutz</dash>
        </description>
        <attribute type="package" value="10">
            <quantity unit="Verpackung" price="15" currency="€">1</quantity>
        </attribute>
    </product>
    <product name="Schraubendreher-Set">
        <image>screwdrivers.pdf</image>
        <description>
            <details>Geeignet für: Schlitz und Kreuzschlitz PH, 12-tlg.</details>
            <dash>Isolierte VDE Klingen für sicheres Arbeiten</dash>
            <dash>Mehrkomponentiger Griff</dash>
            <dash>Mit Griffkennzeichnung zum leichteren Finden</dash>
            <dash>Erhöhter Korrosionsschutz</dash>
        </description>
        <attribute type="package" value="12">
            <quantity unit="Verpackung" price="17" currency="€">1</quantity>
        </attribute>
    </product>
</products>
```

<h2>Der Erstellungsprozess</h2><p>Nun gilt es, diese Daten in ein Layout zu setzen. Hierzu wird eine layout.xml erstellt.</p>

```code-highlighted code-xml
<Layout
  xmlns="urn:speedata.de:2009/publisher/en"
  xmlns:sd="urn:speedata:2009/publisher/functions/en">
</Layout>
```

<p>Ein Layout beginnt grundsätzlich auf Basis eines <code>Layout</code>-Nodes mit dem entsprechendem Namespace. Im Folgenden werden die Sprache des PDFs und die Schriftarten mit ihren einzelnen Definitionen beschrieben.</p>

```code-highlighted code-xml
<Options mainlanguage="German" imagenotfound="warning"/>
  <LoadFontfile name="RubikRegular" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-Regular.otf"/>
  <LoadFontfile name="RubikBold" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-Bold.otf"/>
  <LoadFontfile name="RubikItalic" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-Italic.otf"/>
  <LoadFontfile name="RubikMedium" filename="https://github.com/googlefonts/rubik/raw/masin/fonts/otf/Rubik-Medium.otf"/>
  <LoadFontfile name="RubikLight" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-Light.otf"/>
  <LoadFontfile name="RubikBoldItalic" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-BoldItalic.otf"/>
  <LoadFontfile name="RubikMediumItalic" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-MediumItalic.otf"/>
  <LoadFontfile name="RubikLightItalic" filename="https://github.com/googlefonts/rubik/raw/main/fonts/otf/Rubik-LightItalic.otf"/>
  <DefineFontfamily fontsize="11" leading="12" name="description">
    <Regular fontface="RubikRegular"/>
    <Bold fontface="RubikBold"/>
    <Italic fontface="RubikItalic"/>
    <BoldItalic fontface="RubikBoldItalic"/>
  </DefineFontfamily>
  <DefineFontfamily fontsize="12" leading="13" name="product">
    <Regular fontface="RubikRegular"/>
    <Bold fontface="RubikBold"/>
    <Italic fontface="RubikItalic"/>
    <BoldItalic fontface="RubikBoldItalic"/>
  </DefineFontfamily>
  <DefineFontfamily fontsize="17" leading="19" name="price">
    <Regular fontface="RubikRegular"/>
    <Bold fontface="RubikBold"/>
    <Italic fontface="RubikItalic"/>
    <BoldItalic fontface="RubikBoldItalic"/>
  </DefineFontfamily>
```

<p>Nach diesen Fontregeln gilt es, ein einfaches Tabellenlayout in das PDF zu schreiben. Hierzu werden mittels <code><Record></code> die einzelnen Nodes der Daten-XML angesprochen, wobei eine erste Tabelle erst auf Basis des <code><product></code> -Node erstellt wird. Mittels <code><Switch></code> wird auf Basis von Variablen ein dynamisches Layout in Bezug auf die Produktbeschreibung erzeugt. Für die Nodes <code><dash></code>,<code><attribute></code>und <code><quantity></code> werden die Elemente im PDF per Loops über <code><ForAll></code> erzeugt.</p>

```code-highlighted code-xml
  <Record element="products">
    <ProcessNode select="product"/>
  </Record>
  <Record element="product">
    <SetVariable variable="diameter" select="description/diameter"/>
    <SetVariable variable="type" select="attribute/@type"/>
    <PlaceObject>
      <Table stretch="max">
        <Columns>
          <Column width="1*"/>
          <Column width="2*"/> 
        </Columns>
        <Tr>
          <Td>
            <Image file="{image}"/>
          </Td>
          <Td align="left" valign="top">
            <Paragraph fontfamily="product"><B><Value select="@name"/></B></Paragraph>
            <Paragraph fontfamily="description">
              <Switch>
                <Case test="not(empty($diameter))">
                  <Value select="$diameter"/>
                  <Value> Durchmesser, </Value>
                  <Value select="description/details"/>
                </Case>
                <Otherwise>
                  <Value select="description/details"/>
                </Otherwise>
              </Switch>
            </Paragraph>
            <ForAll select="description/dash">
              <Table max="stretch" fontfamily="description">
                <Columns>
                  <Column width="5mm"/>
                  <Column width="5mm"/>
                  <Column width="1*"/>
                </Columns>
                <Tr valign="top">
                  <Td></Td>
                  <Td>
                    <Paragraph>
                      <Value>• </Value>
                    </Paragraph>
                  </Td>
                  <Td>
                    <Paragraph textformat="justified">
                      <Value select="."/>
                    </Paragraph>
                  </Td>
                </Tr>
              </Table>
            </ForAll>
            <ForAll select="attribute">
              <Switch>
                <Case test="$type != 'package'">
                  <Table>
                    <Tr>
                      <Td></Td>
                      <Td><Paragraph><Value select="@value"/>:</Paragraph></Td>
                    </Tr>
                  </Table>
                  <Table width="5" stretch="max">
                    <Tablehead>
                      <Tr backgroundcolor="gray">
                        <Td><Paragraph><Value>Menge</Value></Paragraph></Td>
                        <Td><Paragraph><Value>Einheit</Value></Paragraph></Td>
                        <Td><Paragraph><Value>Preis</Value></Paragraph></Td>
                      </Tr>
                    </Tablehead>
                    <ForAll select="quantity">
                      <Tr>
                        <Td><Paragraph><Value select="."/></Paragraph></Td>
                        <Td><Paragraph><Value select="@unit"/></Paragraph></Td>
                        <Td><Paragraph><Value select="concat(@price,@currency"/></Paragraph></Td>
                      </Tr>
                    </ForAll>
                  </Table>
                </Case>
                <Otherwise>
                  <Table width="10" stretch="max">
                    <Tr>
                      <Td align="right" height="30"><Paragraph fontface="price"><Value select="concat(quantity/@price,quantity/@currency)"/></Paragraph></Td>
                    </Tr>
                  </Table>
                </Otherwise>
              </Switch>
            </ForAll>
          </Td>
        </Tr>
      </Table>
    </PlaceObject>
  </Record>
```

<p>Das Ergebnis stellt nun einen Produktkatalog mit einem einfachen Tabellenlayout, inklusive Logik, dar. Da bei Erstellung des PDFs die entsprechenden Produktbilder nicht vorhanden waren, wurde diese direkt durch einen Platzhalter ersetzt. Die Erstellung des PDFs dauerte auf einem MacBook Pro (2,3 GHz 8-Core Intel Core i9, 32 GB RAM) genau 0.579982 Sekunden.<br /> <a href="https://media.graphassets.com/DPyBJCDZScSEew8TkZBJ"><img src="https://media.graphassets.com/DPyBJCDZScSEew8TkZBJ" alt="produktkatalog im speedata publisher" /></a> <br /> Wie wir sehen konnten, ist es mithilfe des speedata Publishers recht einfach, auf Basis von Datenstrukturen ein entsprechendes PDF in hoher Geschwindigkeit zu erstellen. Zum Abschluss gilt es nun, die lokale Umgebung in einen Container zu packen.</p><h2>PDFs aus dem Container</h2><p>Leider gibt es noch keinen fertigen Docker-Container, sodass wir direkt loslegen könnten. Daher gilt es, diesen nun zu erstellen.</p>

```code-highlighted code-Docker
FROM ubuntu:latest

ENV DEBIAN_FRONTEND=noninteractive
RUN apt update && apt install -y gnupg openjdk-13-jre-headless inkscape

COPY files/speedata.list /etc/apt/sources.list.d
COPY files/gpgkey-speedata.txt /tmp/gpgkey-speedata.txt
RUN  APT_KEY_DONT_WARN_ON_DANGEROUS_USAGE=1 apt-key add /tmp/gpgkey-speedata.txt

RUN apt update
RUN apt install -y speedata-publisher

WORKDIR /server
ADD files/publisher.cfg /server

ENTRYPOINT [ "sp", "server" ]
```

<p>Im Ordner <em>files</em> befindet sich neben <code>speedata.list</code> und <code>gpgkey-speedata.txt</code> noch die Datei <code>publisher.cfg</code>. Hier wird über Key-/Value-Parameter die Konfiguration des speedata Publishers vorgenommen. Wenn das Image nun mit <code>docker build -t pdf-container</code> und der Container anschließend mittels<code>docker run --rm -p 5266:5266 pdf-container</code> gestartet wurde, verfügt dieser über die nachfolgenden Endpunkte.</p><table><thead><tr><th>Methode</th><th>Endpunkt</th><th>Beschreibung</th></tr></thead><tbody><tr><td>GET</td><td><code>/available</code></td><td>Es wird ein Statuscode 200 zurückgegeben, wenn der Publishing Server verfügbar ist.</td></tr><tr><td>POST</td><td><code>/v0/publish</code></td><td>Es werden Daten an den Server gesendet, um einen Publishing-Lauf zu starten. Eine ID des Publishing-Laufs wird als Rückgabewert geliefert.</td></tr><tr><td>GET</td><td><code>/v0/publish/</code></td><td>Es wird geprüft, ob ein Publishing Prozess beendet ist.</td></tr><tr><td>GET</td><td><code>/v0/pdf/</code></td><td>Es wird auf die Fertigstellung eines PDFs gewartet und das PDF wird heruntergeladen.</td></tr><tr><td>GET</td><td><code>GET/v0/data/</code></td><td>Es wird die data.xml des jeweiligen Publishing-Laufs in Referenz zur angegebenen ID geladen.</td></tr><tr><td>GET</td><td><code>/v0/layout/</code></td><td>Es wird die layout.xml des jeweiligen Publishing-Laufs in Referenz zur angegebenen ID geladen.</td></tr><tr><td>GET</td><td><code>/v0/statusfile/</code></td><td>Es wird die Statusdatei (publisher.status) des jeweiligen Publishing-Laufs in Referenz zur angegebenen ID geladen.</td></tr><tr><td>GET</td><td><code>/v0/status</code></td><td>Es wird eine Übersicht über die laufenden Publishing-Prozesse zurückgegeben.</td></tr><tr><td>GET</td><td><code>/v0/status/</code></td><td>Es wird eine Übersicht über einen laufenden Publishing-Prozess in Referenz zur angegebenen ID zurückgegeben.</td></tr><tr><td>POST</td><td><code>/v0/delete/</code></td><td>Es wird ein Publishing-Lauf in Referenz zur angegebenen ID gelöscht.</td></tr></tbody></table><p>Mit <code>/v0/publish</code> können wir nun Daten und das Layout an den „PDF-Container“ senden. Diese müssen in einer JSON-Datei base64-kodiert hinterlegt werden. Was bezogen auf unser Beispiel folgendermaßen aussehen würde.</p>

```code-highlighted code-json
{
    "layout.xml": "...",
    "data.xml": "..."
}
```

<p>Als Rückgabe erhalten wir eine ID mit Statuscode 201 zurück. Mithilfe dieser ID können wir nun dem GET-Request <code>v0/pdf/<id></code> das PDF vom Server laden. Durch Setzen des Parameters <code>delete</code> auf den Wert <code>false</code> wird das PDF nicht vom Server gelöscht.</p><h2>Fazit</h2><p>Mit dem speedata Publisher können wir auf recht einfache Art und Weise PDFs erzeugen und diesen Erstellungsprozess, vor allem aufgrund eines Containers, in bestehende Entwicklungsprojekte einbinden. Das Beispiel und das Dockerfile sind in <a href="https://github.com/danielkocot/containerized_pdf_rendering" target="_blank">GitHub</a>  zu finden.</p>

PDF-Generierung aus dem Container – speedata Publisher

<p><span>Wenn man sich mit der Entwicklung von Microservices und der Konnektivität dieser beschäftigt, stolpert man unweigerlich über Begriffe / Muster von API Gateway und Service Mesh. Aber warum gibt es diese Patterns bzw. Technologien überhaupt? Manchmal passiert es auch, dass die Patterns inhaltlich miteinander vertauscht werden, da ein vertieftes Verständnis für die Anwendung der Patterns fehlt und ein Tutorial nicht unbedingt die beste Grundlage bildet. Zu Beginn ist es wichtig, erstmal einen Blick auf das OSI-Netzwerkschichtenmodell zu werfen. Dieses Modell stellt die Grundlage für alle nachfolgenden Überlegungen dar.</span></p><h2>OSI-Netzwerkschichtenmodell</h2><p><a href="https://media.graphassets.com/HfJ2IerRQlKoXiIjmm0E"><img src="https://media.graphassets.com/HfJ2IerRQlKoXiIjmm0E" alt="OSI Model" width="1024" height="768" /></a> <br /> Das Modell beschreibt als Referenz die entsprechenden Netzwerkprotokolle in Form von Schichten. Im Laufe des Blogposts werden wir immer wieder auf dieses Modell zurückkommen.<br /> In <a href="https://blog.codecentric.de/?s=kong+api+gateway&x=0&y=0">verschiedenen Blogposts</a>  wurde das API Gateway schon im Detail beschrieben, hier sollen die wichtigsten Punkte für einen möglichen Vergleich mit einem Service Mesh nun zusammengefasst werden.</p><h2>API Gateway</h2><p>Ein API Gateway fungiert als einziger Zugriffspunkt in einem Cluster, einem Datenzentrum oder für eine Gruppe von verteilten Diensten. In der Netzwerktopologie wird dies oft als North-South-Traffic bezeichnet. Typischerweise benutzen mobile Clients diese Art von Netzwerkverkehr.<br /> Es ist auch durchaus möglich, dass man API Gateways für die Kommunikation zwischen zwei im selben Rechenzentrum eingesetzten Produkten verwendet. In diesem Fall kann es auch zu einem East-West-Traffic kommen.<br /> Ein API Gateway nimmt Aufrufe von Routen entgegen und leitet diese an entsprechende Dienste weiter. Dabei kann es u.a. auch Protokolle übersetzen.</p><table><thead><tr><th><strong>Die Verwendung eines API Gateways bietet verschiedene Vorteile:</strong></th></tr></thead><tbody><tr><td><em><strong>Abstraktion</strong></em>: Ein API Gateway kann die Komplexität der darunter liegenden (Mikro)services abstrahieren und eine einheitliche Sicht für die Konsumenten der APIs schaffen.</td></tr><tr><td><em><strong>Authentifizierung / Autorisierung</strong></em>: Ein API Gateway kann sich um die Authentifizierung kümmern und u.a. die Token-Informationen an die Dienste weiterleiten.</td></tr><tr><td><strong><em>Rate-Limiting</em></strong>: Ein API Gateway kann eingehenden und ausgehenden API-Traffic drosseln</td></tr><tr><td><strong><em>API-Monitoring</em></strong>: Ein API Gateway kann Monitoring auch auf Grundlage bestimmter Metriken des ein- und ausgehenden Traffics vornehmen.</td></tr><tr><td><strong><em>Monetarisierung</em></strong>: Ein API Gateway kann auch bei der Entwicklung von Monetarisierungsregeln hinsichtlich der Nutzung der APIs unterstützen. Dies basiert dann nicht nur auf den Metriken aus dem Monitoring.</td></tr><tr><td><strong><em>Transformationen</em></strong>: Ein API Gateway kann bei der Übersetzung/Transformation von API-Anfragen/Antworten unterstützen. Hierbei sollten aber nur Transformationen von Protokollen, wie beispielsweise XML zu JSON, vorgenommen werden.</td></tr></tbody></table><p>Zusammenfassend konzentrieren sich API Gateways auf die Kommunikation der Applikationsschicht bzw. Layer 7 nach dem OSI-Modell.</p><h3>Arten von API-Gateways</h3><p>Aus der Einsatzperspektive gibt es zwei Möglichkeiten, API Gateways zu verwenden:<br /> – <strong><em>Interne API Gateways</em></strong>: fungieren als Gateway für eine Gruppe von Diensten oder ein entsprechendes <a href="https://blog.codecentric.de/2018/10/api-as-a-product/">API-Produkt</a> <br /> – <em><strong>Edge-API Gateway</strong></em>: dient als Gateway für Kunden von externen Organisationen</p><h2>Service Mesh</h2><p>Ein Service Mesh ist ein Technologieansatz, der die Service zu Service Kommunikation innerhalb eines verteilten Softwaresystems verwaltet. Service Meshes sollen im Regelfall den East-West-Typ der Netzwerkkommunikation verwalten. East-West-Traffic zeigt einen Verkehrsfluss innerhalb eines Datenzentrums, Kubernetes-Clusters oder eines verteilten Systems an.<br /> Service Meshes bestehen aus zwei wichtigen Komponenten:<br /> – <em><strong>Control Plane</strong></em><br /> – <em><strong>Data Plane</strong></em><br /> Die sogenannten Sidecar Proxys, die gemeinsam mit dem jeweiligen Service betrieben werden, bezeichnet man als Data Plane.<br /> <a href="https://media.graphassets.com/XoLaigrTxqGpO7q5GILt"><img loading="lazy" width="887" height="629" src="https://media.graphassets.com/XoLaigrTxqGpO7q5GILt" alt="Concept Service Mesh" /></a> <br /> Ein Service Mesh ermöglicht, die Geschäftslogik der Anwendung von Themen des sogenannten Off-Loadings zu trennen.</p><table><tbody><tr><th><strong>Info: Off-Loading</strong></th></tr><tr><td>Unter Off-Loading fasst man die Elemente der Cross-Cutting Concerns zusammen, wie Zertifikatsverwaltung, Authentifizierung, SSL-Terminierung, Überwachung, Protokollübersetzung oder Drosselung.</td></tr></tbody></table><h3>Netzwerk- und Trafficmanagement</h3><p>Durch den Einsatz eines Service Mesh lässt sich eine dynamische Service-Discovery durchführen. Ein Sidecar-Proxy unterstützt beim Load-Balancing, Rate-Limiting und beim Routing des Traffics, um z.B. einen A/B-Test durchzuführen, was bei einem Canary Release hilfreich sein kann.</p><h3>Monitoring und Resilience</h3><p>Ein Service Mesh unterstützt <em>distributed traceability</em>, was das Monitoring bezogen auf die Anzahl der Requests, Success Rates, Responselatenzen und somit die Fehlersuche einbezieht. Da das Service Mesh Health-Checks, Retrys, Timeouts und Circuit-Breaking bietet, verbessert es die Zuverlässigkeit der Anwendung.</p><h3>Sicherheit</h3><p>Ein Service Mesh ermöglicht ein gegenseitiges TLS zwischen den Diensten, was dazu beiträgt, die Sicherheit der Service-zu-Service-Kommunikation zu erhöhen. Ebenfalls lassen sich auch Zugriffe über ACLs als Sicherheitsrichtlinien implementieren.<br /> Zusammenfassend decken Service Meshes die Kommunikation in der Transport- und Applikationsschicht, bzw. Layer 4 und 7 nach dem OSI-Modell, ab.</p><h2>Was kann man wann und wie verwenden?</h2><p>Hierzu soll ein Blick auf konkrete Anwendungsszenarien geworfen werden, um auszuloten, welche Komponente zielgerichtet verwendet werden kann.</p><table><thead><tr><th>Szenario</th><th>API Gateway</th><th>Service Mesh</th></tr></thead><tbody><tr><td>API als Produkt mit/ohne Monetarisierung</td><td>X</td><td></td></tr><tr><td>L7-Service-Kommunikation mit Sicherheit und Überwachung über verschiedene API-Produkte hinweg</td><td>X</td><td></td></tr><tr><td>L4/L7-Servicekommunikation mit Sicherheit und Überwachung innerhalb desselben API-Produkts</td><td></td><td>X</td></tr><tr><td>Entwicklern ein vollständiges Lifecycle-Management der API anbieten</td><td>X</td><td></td></tr><tr><td>Sichere Kommunikation zwischen Services</td><td></td><td>X</td></tr><tr><td>Transformation von Kommunikationsprotokollen</td><td>X</td><td></td></tr></tbody></table><p>Bei Betrachtung der einzelnen Szenarien stellt sich auch die Frage, wie API Gateway und Service Mesh zusammenarbeiten könnten. Aus diesem Grund soll zum Abschluss genau dieses Zusammenspiel näher betrachtet werden.<br /> <img loading="lazy" width="1024" height="733" src="https://media.graphassets.com/jqQd5iRwS9C4cpDncVEy" alt="API Gateway and Service Mesh" /><br /> Das API Gateway gewährt hier Zugriff auf die einzelnen API Services. Dahinter befinden sich nun, aufgeteilt in zwei Schichten der Composite/Integration und der Core-Schicht, die Services für die Business-Logik. Die Kommunikation der einzelnen Services findet über die Sidecar Proxy an den jeweiligen Services statt.</p><h2>Fazit</h2><p>API Gateways und Service Meshes können ein Bestandteil von Softwarearchitekturen sein und werden. Es ist aber wichtig, den jeweiligen Use Case genau zu betrachten, um entsprechende Technologien einsetzen zu können.</p>

API Gateway und Service Mesh im Kontext von Service-Konnektivität

<p>In den vorangegangenen Posts taucht immer wieder der Begriff <em>API first</em> und wurde immer dem „Anlass“ entsprechend verwendet. In Vorbereitung auf andere neue Posts bemerkte ich, dass es nun an der Zeit ist, den Begriff in all seinen Facetten zu betrachten. Was ist also mit dem Ansatz „API first“ gemeint?</p><p>Zu Anfang aber erstmal ein ziemlich aktuelles Zitat:</p><blockquote><p>don’t think that #APIfirst only works if you design your #API first. the important aspect is to always <strong>think</strong> about your #API and its value first.</p></blockquote><p>— Erik Wilde, <cite>Twitter 10.07.2021, <a href="https://twitter.com/dret/status/1413877272344469511" target="_blank">https://twitter.com/dret/status/1413877272344469511</a> </cite></p><p>Das was <a href="https://twitter.com/dret" target="_blank">Erik Wilde</a>  hier beschreibt, stimmt absolut. Grundsätzlich gilt es vor jedem Schritt in Richtung einer Beschreibung und anschließender Umsetzung einer API zu überlegen, welchen Wert bzw. Stellenwert diese API für die Unternehmung haben wird. Wenn dies geklärt ist, macht es Sinn, die weiteren Schritte in Richtung API first zu gehen. Dies funktioniert auch wenn es schon eine Implementierung für eine solche API existiert.</p><p>Wenn man nun API first bei Software-Entwicklungsteams einführen möchte, gilt es, die folgenden drei Prinzipien voranzustellen.</p><ol><li>Die API ist die erste Benutzerschnittstelle der Anwendung.<div><p>Die API muss mit dem klaren Fokus auf den Endanwender entwickelt werden. Entwickler müssen der Gestaltung und Pflege einer API die gleiche Aufmerksamkeit zuwenden, wie sie es bei UX und der grafischen Benutzeroberfläche tun.</p></div></li><li>Die API steht an erster Stelle – vor der Implementierung.<div><p>Durch Weiterentwicklung, Optimierung oder Umstrukturierung kann die Applikation an Funktionalität dazu gewinnen. Ihre API sollte konsistent bleiben. Die API sollte von der Implementierung getrennt behandelt werden. So kann die API zu einem Vertrag werden, der die Implementierung steuert, anstatt nur über der Implementierung zu schweben.</p></div></li><li>Die API wird erläutert (und ist sogar selbsterklärend).<div><p>Um möglichst schnell und effizient zu sein, muss die API auch für andere, die nicht an ihrer Erstellung beteiligt waren, leicht verständlich sein. Eine brauchbare API-Dokumentation ist die Grundlage, um Inhalte so zu übersetzen, dass sie konsumiert werden können. Dies bedeutet eine strukturierte Dokumentation, die Standardmustern für Elemente wie URLs, Anfragemethoden, Header, Parameterabfragen und zuständige Formate folgt.</p></div></li></ol><p>Eine detaillierte Darstellung der drei Prinzipien findet man in einem <a href="https://medium.com/adobetech/three-principles-of-api-first-design-fa6666d9f694" target="_blank">Post von Lars Trieloff</a>  (Principal bei Adobe).</p><h2>Was sind denn die wirklichen Vorteile von API first?</h2><ol><li><h3>Parallele Softwareentwicklung</h3><div><p>Einer der größten Vorteile von API first für Entwickler und Projektbeteiligte ist die Möglichkeit der parallelen Entwicklung. Wenn man also mit dem Design von APIs beginnt, kann man sicher sein, dass dies zu einer soliden Basis für das angestrebte Produkt führt. So kann sich das Entwicklungsteam bereits in frühen Iterationen auf die IT-Infrastruktur des Produkts konzentrieren. APIs können gleichzeitig entwickelt und getestet werden. Die Teammitglieder arbeiten parallel, was eine Zusammenarbeit in Echtzeit und schnellere Feedback-Zyklen bedeutet. Als Ergebnis werden APIs schnell entworfen, implementiert und dokumentiert, bevor die Kanäle, die sie nutzen werden, eingerichtet werden.</p></div></li><li><h3>Verbesserte API-Experience</h3><div><p>Bei der Entwicklung einer API ist es wichtig, die Erfahrung des Benutzers in den Vordergrund zu stellen. AX nimmt einen Anwender als Verbraucher, Intermediär oder Endnutzer eines Produkts (einer API) wahr. Dies macht Anwender zu einem Schlüsselelement der Wertschöpfungskette. Sie erstellen APIs und nutzen sie sowohl zum Vorteil des Verbrauchers als auch zum Vorteil des Unternehmens.</p></div><div><p>Bei einem API-first-Ansatz geht es darum, dass der Fokus mehr auf dem API-Produkt und weniger auf der Technologie liegt. Daher ist es sinnvoll, eine API zu haben, die funktional ist und von Anwendern leicht genutzt werden kann. Das Ziel einer API ist es, ein reichhaltiges Ökosystem zu schaffen, in dem Anwender mühelos Informationen erhalten und darauf aufbauend Anwendungen erstellen können.</p></div></li><li><h3>Der beschleunigte Entwicklungsprozess</h3><div><p>APIs beschleunigen den Entwicklungsprozess. Auf den ersten Blick mag es so aussehen, als würde eine API-first-Strategie zu Verzögerungen bei der Markteinführung führen: Anstatt direkt mit dem Schreiben von Code zu beginnen, verbringt das Team Zeit mit der blockierenden Aufgabe der API-Entwicklung. Dem ist jedoch nicht so. Dieser Ansatz ermöglicht die Wiederverwendung bestehender Software und Infrastruktur, was zu schnelleren Softwarelieferungen in der Zukunft führt. Durch die Integration bestehender Komponenten können Prozesse verbessert werden, um eine Beschleunigung der Markteinführung zu ermöglichen.</p></div><div><p>Somit ermöglicht ein API-first-Ansatz einem Unternehmen, die gesamte Entwicklungszeit zu optimieren. Agilität kann auch dann erreicht werden, wenn die API nicht alle Funktionen des Systems abdeckt. Durch die schnelle Erstellung einer ersten API für eine Anwendung werden auch die ersten Iterationen bei der Entwicklung der Schnittstelle beschleunigt. Sobald die initiale API definiert ist, ist es einfacher, sie zu erweitern und zu verbessern und neue Funktionen hinzuzufügen. Der Schlüssel ist, Lösungen für die häufigsten Anwendungsfälle anzubieten und eine intuitive Schnittstelle für die Arbeit mit mehreren Datenquellen zu schaffen.</p></div></li><li><h3>Geringere Ausfallrisiken</h3><div><p>Ein nicht nachhaltiges System, das ein inkonsistentes Kundenerlebnis bietet, hat in der Regel ein hohes Risiko des Scheiterns. Dies ist kein Problem für Teams, die zunächst APIs entwickeln. APIs sind nicht nur die Art und Weise, in der sich Unternehmen darstellen, sondern sie ermöglichen es Organisationen auch, schnell zu wachsen und sich an die sich ändernden Benutzeranforderungen anzupassen. Es ist die Agilität, die Teil einer API-first-Strategie ist, die es ermöglicht, sich schnell an veränderte Anforderungen anzupassen und die Endbenutzer umfassender in den Entwicklungsprozess einzubeziehen.</p></div><div><p>Teams, die einen API-first-Ansatz verfolgen, haben in der Regel eine produktbezogene Denkweise. Das bedeutet, dass sie sich darüber im Klaren sind, dass sich das Produkt in der Zukunft weiterentwickeln kann, und dass das gesamte Spektrum der Anwendungsfälle für ihre API möglicherweise nicht von Anfang an klar ist. Aber sie sind bereit, ihre Produkte zu iterieren, um den Benutzern schließlich das zu geben, was sie benötigen. Außerdem sind sie erfahren genug und bereit, zunächst eine konsistente und selbstbeschreibende API zu erstellen, auf die sie sich verlassen können. Durch den Vorteil der Flexibilität, die es erlaubt, das Verhalten der Kunden besser zu verstehen und das Produkt mit einem wesentlich geringeren Risiko des Scheiterns weiter zu verfeinern.</p></div></li><li><h3>Optimierte Entwicklungskosten</h3><div><p>In der Regel reduzieren APIs selbst keine Kosten. Sie unterstützen jedoch ein breiteres internes Refactoring von Wertschöpfungsketten. Und das ist es, was tatsächlich zur Kostensenkung beiträgt. Der Aufbau eines Ökosystems von APIs als Produkte und Kanäle macht den Code erweiterbar und wiederverwendbar. Wenn also die App-Entwicklung mit dem Aufbau von APIs beginnt, stellt das Team die Wiederverwendbarkeit und Effizienz des Codes sicher. Das macht APIs zur Kerntechnologie in der digitalen Wertschöpfungskette. Erfolgreiche Unternehmen sehen ihre APIs als Ressourcen, die andere Funktionen in der Wertschöpfungskette ermöglichen, und das nicht umsonst.</p></div><div><p>Wenn es um einen API-first-Ansatz geht, ist eine der wichtigsten Metriken die Geschwindigkeit, mit der digitale Erlebnisse erstellt werden. Manchmal hat sie direkten Einfluss auf die Entwicklungskosten, manchmal auch nicht. Die Quintessenz ist jedoch, dass ein Team, das zuerst APIs entwickelt, um das Business zu unterstützen, anstatt sich auf die Feinheiten der Implementierung dieser APIs zu konzentrieren, dem Kern, dem Fundament seines Projekts mehr Aufmerksamkeit schenkt. Es gibt eine Basisarchitektur vor, mit der man arbeiten kann, und sichert sich so gegen zu hohe Ausgaben in der Zukunft ab.</p></div></li></ol><div><h2>Zusammenfassung</h2><p>Ein API-first-Ansatz kann einen starken Einfluss darauf haben, wie zuverlässig interne und externe Kunden mit Diensten interagieren. Der Ansatz bietet Transparenz, Skalierbarkeit, Leistung und Kostenvorteile. Die Art und Weise, wie APIs angenommen, wahrgenommen und konsumiert werden, ist von großer Bedeutung. Und ein API-first-Ansatz kann die Art und Weise, wie ein Unternehmen seine Infrastruktur organisiert, tatsächlich zum Positiven verändern.</p></div>

API first in allen Facetten

<p>In verschiedenen Posts bin ich auf das Paradigma <em>API first</em> eingegangen. Im letzten <a href="https://blog.codecentric.de/2021/07/api-first-in-allen-facetten/">Post</a>  habe ich <em>API first</em> in Gänze betrachtet.<br /> Nun möchte ich in der Rolle eines API Producers versuchen, einen Service mit der Idee von API first in die Praxis umzusetzen. Konkret geht es um die Erstellung eines Spring-Boot-Services, der über ein API mit dem Endpunkt „/api/news“ eine Liste von Nachrichten liefern soll.</p><p>Zu Beginn steht die Erstellung der OpenAPI-Spezifikation im Fokus. Sie bildet den Ausgangspunkt für jeglichen später generierten Code. Die Spezifikation ist sehr einfach gehalten und stellt sich folgendermaßen dar:</p>

```highlight
openapi: 3.0.3
servers:
  - url: 'http://localhost:8080/api'
info:
  version: 1.0.0
  title: News API
  contact:
    name: Daniel Kocot
    url: 'http://www.codecentric.de'
    email: daniel.kocot@codecentric.de
  license:
    name: MIT
    url: https://www.tldrelgal.com/mit
  description: An API to provide news
tags:
  - name: news
paths:
  /news:
    get:
      description: gets latest news
      operationId: getNews
      tags:
        - news
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleList'
              examples: {}
        '404':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ArticleList:
      title: ArticleList
      type: array
      items:
        $ref: '#/components/schemas/Article'
    Article:
      title: Article
      description: A article is a part of a news.
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        date:
          type: string
          format: date
        description:
          type: string
        imageUrl:
          type: string
      required:
        - id
        - title
        - date
        - description
        - imageUrl
    Error:
        type: object
        properties:
          code:
            type: string
          messages:
            type: string
        required:
          - code
          - message
  securitySchemes: {}
  examples:
    news:
      value:
        description: Example shared example
        type: object
        properties:
          id:
            type: string
        required:
          - id
```

<p>Die Spezifikation wurde mithilfe von <a href="https://stoplight.io/studio" target="_blank">Stoplight Studio</a>  erstellt und basiert auf OpenAPI in der Version <a href="https://spec.openapis.org/oas/v3.0.3.html" target="_blank">3.0.3</a> . Stoplight Studio bietet eine Integration mit GitHub, somit lassen sich die Modelle und Spezifikationen einfacher versionieren. Im <a href="https://github.com/codecentric/api-showcases" target="_blank">GitHub-Repo</a>  selbst ist auch eine GitHub Action konfiguriert, die bei Pushes auf den <em>main</em>-Branch oder Pull Requests auf diesen die Spezifikationen per <a href="https://stoplight.io/open-source/spectral/" target="_blank">Spectral</a>  Linter überprüft. Um den Blogpost nicht zu sprengen, werden wir bei Spectral auf das eingebaute Ruleset zurückgreifen. Spectral kommt auch gleichzeitig als Linter im Stoplight Studio zum Einsatz.<br /> Nachdem die OpenAPI Spec zur Verfügung steht, kann ein Service auf Basis von Spring Boot und Gradle erstellt werden. Die <code>gradle.build</code>-Datei sieht dabei wie folgt aus:</p>

```highlight
plugins {
    id 'org.springframework.boot' version '2.5.2'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'de.undercouch.download' version '4.1.2'
    id 'io.openapiprocessor.openapi-processor' version '2021.3'
    id 'java'
}

group = 'de.codecentric'
version = '0.0.2-SNAPSHOT'
sourceCompatibility = '11'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-data-rest'
    implementation 'org.springframework.boot:spring-boot-starter-web'

    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    runtimeOnly 'com.h2database:h2'

    testImplementation('org.springframework.boot:spring-boot-starter-test')
    testImplementation('org.junit.jupiter:junit-jupiter-api:5.7.2')
    testRuntime('org.junit.jupiter:junit-jupiter-engine:5.7.2')
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

test {
    useJUnitPlatform()
}

task downloadFile(type: Download) {
    src "https://raw.githubusercontent.com/codecentric/api-showcases/main/specs/news.yaml"
    dest "${projectDir}/src/api"
    onlyIfModified true
    useETag true
}

openapiProcessor {
    spring {
        processor 'io.openapiprocessor:openapi-processor-spring:2021.5'
        apiPath "$projectDir/src/api/news.yaml"
        targetDir "$projectDir/build/openapi"
        mapping "$projectDir/mapping.yaml"
        showWarnings true
    }
}

afterEvaluate {
    tasks.processSpring.dependsOn(tasks.downloadFile)
}

sourceSets {
    main {
        java {
            srcDir "build/openapi"
        }
    }

    test {
        resources {
            srcDir file('src/test/java')
            exclude '**/*.java'
        }
    }
}

compileJava.dependsOn('processSpring')

springBoot {
    mainClassName = "de.codecentric.apifirstspringboot.ApifirstSpringbootApplication"
}
```

<p>Für die Generierung des Modells und Interfaces des API werden zwei Plug-ins benötigt. Dadurch, dass sich die Spezifikation in einem Repository auf GitHub befindet, wird ein Download-Task benötigt. Dieser wird durch das Plug-in von <a href="https://github.com/michel-kraemer/gradle-download-task" target="_blank">Michel Krämer</a>  zur Verfügung gestellt. Für den eigentlichen Generierungsschritt wird nicht der OpenAPI Generator, sondern <a href="https://docs.openapiprocessor.io/oap/home/home.html" target="_blank">OpenAPI Processor</a>  verwendet. OpenAPI Processor ist ein ziemlich schlankes Framework, das die OpenAPI-YAML-Datei in ein auszuwählendes Zielformat konvertiert. Neben dem Plug-in für Gradle ist auch eines für Maven erhältlich. Aktuell gibt sogenannte Prozessoren für die folgenden Zielformate:</p><ul><li>Spring</li><li>Micronaut</li><li>JSON</li></ul><p>Die Konvertierung der OpenAPI Spec wird mittels einer <code>mapping.yaml</code> konfiguriert. Für diesen Post wird nur eine simple Konfiguration verwendet.</p>

```highlight
openapi-processor-mapping: v2

options:
  package-name: de.codecentric.generated.news

map:
  result: org.springframework.http.ResponseEntity

  types:
    - type: array => java.util.List
```

<p>Um die Konvertierung ein erstes Mal zu starten, reicht <code>gradle clean compileJava</code>. Nun stehen die Modelle und das Interface im Package <code>de.codecentric.generated.news</code> zur Verfügung. Um nicht direkt auf das API-Modell der Artikel-Entität zuzugreifen, empfiehlt es sich, eine separate Entität zu erstellen. Es kann auch sein, dass die Entität nicht 1:1 dem API-Modell entspricht. Im Beispiel enthält die Artikel-Entität ein weiteres Attribut <em>Author</em>, das nicht über API nach außen gegeben wird. Um ein Mapping zwischen der Entität und dem Model herzustellen, wird eine entsprechende Mapper-Klasse erstellt.</p>

```highlight
package de.codecentric.apifirstspringboot.mapper;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import de.codecentric.apifirstspringboot.entities.Article;

import java.util.List;
import java.util.stream.Collectors;

public class ArticleModelMapper {

    private static ObjectMapper objectMapper = new ObjectMapper();

    public static Article toEntity(de.codecentric.news.api.model.Article article) {
        return Article.builder()
                .description(article.getDescription())
                .title(article.getTitle())
                .date(article.getDate())
                .imageUrl(article.getImageUrl())
                .build();
    }

    public static de.codecentric.news.api.model.Article toApi(Article article) {
        de.codecentric.news.api.model.Article articleModel = new de.codecentric.news.api.model.Article();
        articleModel.setId(article.getId());
        articleModel.setTitle(article.getTitle());
        articleModel.setDate(article.getDate());
        articleModel.setDescription(article.getDescription());
        articleModel.setImageUrl(article.getImageUrl());

        return articleModel;
    }

    public static List<de.codecentric.news.api.model.Article> toApi(List<Article> retrieveAllArticles) {
        return retrieveAllArticles.stream()
                .map(ArticleModelMapper::toApi)
                .collect(Collectors.toList());
    }

    public static de.codecentric.news.api.model.Article jsonToArticle(String json) throws JsonProcessingException {
        return objectMapper.readValue(json, de.codecentric.news.api.model.Article.class);
    }
}
```

<p>Ebenso kann auch ein Framework wie <a href="https://mapstruct.org/" target="_blank">Mapstruct</a>  für das Mapping zum Einsatz kommen.<br /> Um nun ein API über den Service nach außen zur Verfügung zu stellen, wird noch eine Repository- und eine Controller-Klasse benötigt.</p>

```highlight
package de.codecentric.apifirstspringboot.repository;

import de.codecentric.apifirstspringboot.entities.Article;
import org.springframework.data.jpa.repository.JpaRepository;

public interface NewsRepository extends JpaRepository<Article, Long> {

}
```

<p>Der Controller wird das generierte API Interface implementieren.</p>

```highlight
package de.codecentric.apifirstspringboot.controller;

import de.codecentric.apifirstspringboot.service.NewsService;
import de.codecentric.generated.news.api.NewsApi;
import de.codecentric.generated.news.model.Article;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import java.util.List;

import static de.codecentric.apifirstspringboot.mapper.ArticleModelMapper.toApi;

@Controller
@RequestMapping("/api")
public class NewsController implements NewsApi {

    private NewsService newsService;

    public NewsController(NewsService newsService) {
        this.newsService = newsService;
    }

    @Override
    public ResponseEntity<List<Article>> getNews() {
        List<de.codecentric.apifirstspringboot.entities.Article> allArticles = newsService.retrieveAllArticles();
        return ResponseEntity.ok().body(toApi(allArticles));
    }
}
```

<p>Auf Basis von <code>schema.sql</code> und <code>data.sql</code> liefert der Endpunkt <code>/api/news</code> folgenden JSON-Response zurück.</p>

```highlight
[
    {
        "date": "2021-07-08",
        "description": "codecentric is...",
        "id": 1,
        "imageUrl": "http://picserve.codecentric.de/1/bild",
        "title": "Company news"
    }
]
```

<h2>Fallstricke: OpenAPI Spec</h2><p>Zum Schluss möchte ich noch auf zwei Fallstricke eingehen, die im Laufe der Entwicklung aufgetaucht sind. Zuallererst sollte aufgefallen sein, dass nicht die neuste OpenAPI-Spezifikation verwendet wird. Dies liegt darin begründet, dass die Parser im Java-Umfeld (swagger und openapi4j) nur OpenAPI Spec 3.0 (genauer 3.0.3) unterstützen. Dies betrifft dann auch andere Code-Generatoren, wie den OpenAPI-Generator.<br /> Wenn man sich für die Entwicklung auf Basis von API first entscheidet, ist es wichtig im Auge zu behalten, welche Version der Spezifikation schon von den Generatoren unterstützt wird.<br /> In der OpenAPI Spec enthält die URL des Servers auch den Basispfad (<code>/api</code>). Das Feld <code>servers.url</code> wird vom OpenAPI Processor nicht ausgelesen. Hier gibt es nun zwei Lösungsvarianten. Entweder wird der Basispfad immer bei den <code>paths</code> hinterlegt oder dieser muss im Controller für das API als Annotation per Hand hinterlegt werden. Im <a href="https://github.com/codecentric/spring-boot-api-first" target="_blank">Repo</a>  findet sich die zweite Variante wieder.</p><h2>Zusammenfassung</h2><p>Es ist festzustellen, dass es mit Einschränkungen möglich ist, auf Basis der Idee von API first Services mit Spring Boot zu entwickeln. Wenn man sich der aktuellen Fallstricke auch bewusst ist, wird es gelingen, Services in entsprechender Geschwindigkeit und Güte verfügbar zu machen.</p>

API-first-Services mit Spring Boot

<p>In unseren Projekten sind wir auf Dokumentation angewiesen, auch wenn immer noch viele Menschen, von der Annahme ausgehen, dass aufgrund des Agilen Manifests keine Dokumentation mehr benötigt wird ;). Was das Tooling in Sachen Dokumentation angeht, treffen wir in Projekten sehr häufig auf Confluence. Dieses System liefert aufgrund einer Vielzahl von Plugins sehr viele Möglichkeiten einer Integration in den Dokumentationsprozess. Wobei ein Wiki eigentlich immer den letzten Schritt in einer Dokumentationskette darstellt, da es sich im klassischen Sinne um einen Wissensspeicher handelt und nicht um wirkliche projektbezogene lebende Dokumentation. In den letzten Jahren ist immer mehr die „docs-as-code“-Bewegung in Erscheinung getreten. Hierbei geht es darum, Dokumentation nah in den Entwicklungsquellen zu halten und diese auf Basis von leichtgewichtigen Markup-Sprachen, wie <a href="https://www.markdownguide.org" target="_blank">Markdown</a>  und <a href="https://asciidoctor.org" target="_blank">Asciidoc(tor)</a> , zur Verfügung zu stellen. Und genau dieses „docs-as-code“ wird auch immer mehr Teil von Produkten und Plattformen wie Gitlab und Azure DevOps. Azure DevOps geht hier sogar einen neuen Weg. Auf Basis eines Git-Repositories wird ein Wiki bereitgestellt. Die Inhalte lassen sich mittels Markdown erstellen. Mit diesem Wiki haben wir für uns nun eine erste Möglichkeit um „docs-as-code“ in einem Projekt zu etablieren. Azure geht noch einen kleinen Schritt weiter und erweitert „docs-as-code“ mit dem integrierten <a href="https://mermaid-js.github.io/mermaid/">Mermaid</a>  um „diagrams-as-code“. Bei „diagrams-as-code“ werden wir mit Hilfe einer DSL in die Lage versetzt Diagramme, innerhalb eines Repositories und somit versioniert, zu erstellen.</p><h2>Mermaid</h2>

```highlight
sequenceDiagram
    loop Daily query
        Alice->>Bob: Hello Bob, how are you?
        alt is sick
            Bob->>Alice: Not so good :(
        else is well
            Bob->>Alice: Feeling fresh like a daisy
        end

        opt Extra response
            Bob->>Alice: Thanks for asking
        end
    end
```

<p>Soweit so gut. Leider schafft es Microsoft seit fast zwei Jahren nicht auf die aktuellste Version von Mermaid zu aktualisieren (<a href="https://developercommunity.visualstudio.com/t/mermaid-support-for-class-diagrams-and-state-diagr/883356" target="_blank">Developer-Community</a> ). Somit können wir nicht die aktuellsten Features von Mermaid benutzen, sondern haben nur die Möglichkeit Flowcharts, Sequenzdiagramme oder Gant-Charts zur Auswahl.</p><h2>PlantUML</h2><p>Da ich in meinem aktuellen Projekt sehr viel mit Entity-Relationship Modellen arbeite und für die Darstellung in der Regel auf <a href="https://plantuml.com/de/" target="_blank">PlantUML</a>  setze, wollte ich dies auch gerne wieder verwenden.</p>

```highlight
@startuml

' hide the spot
hide circle

' avoid problems with angled crows feet
skinparam linetype ortho

entity "Entity01" as e01 {
  *e1_id : number <<generated>>
  --
  *name : text
  description : text
}

entity "Entity02" as e02 {
  *e2_id : number <<generated>>
  --
  *e1_id : number <<FK>>
  other_details : text
}

entity "Entity03" as e03 {
  *e3_id : number <<generated>>
  --
  e1_id : number <<FK>>
  other_details : text
}

e01 ||..o{ e02
e01 |o..o{ e03

@enduml
```

<p>Leider ist eine direkte Integration in das Azure DevOps Wiki aktuell für PlantUML nicht vorgesehen. Hier gilt es nun eine Lösung zu finden, die uns hilft dem Ansatz von „docs-as-code“ in Gänze gerecht zu werden. Da „docs-as-code“ grundsätzlich auf Basis einer Pipeline entstehen, werden wir versuchen die Grafiken und Diagramme auf genau dieser Basis zu generieren. Da PlantUML als JAR ausgeliefert wird, müssen wir für die Pipeline eine entsprechende Laufzeitumgebung zur Verfügung stellen. Dies geschieht in Form eines Docker-Image. Welches wir dann innerhalb der Pipeline als Container zur Verfügung stellen. Das entsprechende Image findet Ihr im <a href="https://hub.docker.com/r/codecentric/plantuml-docker" target="_blank">Docker Hub</a> . Im <a href="https://github.com/codecentric/plantuml-docker" target="_blank">Git Repo</a>  findet Ihr auch das folgende Dockerfile, welches die Grundlage des Image ist:</p>

```highlight
FROM docker.io/alpine:3
LABEL maintainer="Daniel Kocot <daniel.kocot@codecentric.de>" \
      description="Internal Docker image for PlantUML"

ENV PLANTUML_VERSION 1.2021.16

RUN apk update
RUN apk add --no-cache graphviz openjdk8-jre curl ttf-droid
RUN mkdir /app
RUN curl -L https://sourceforge.net/projects/plantuml/files/plantuml.${PLANTUML_VERSION}.jar/download -o /app/plantuml.jar
RUN apk del curl

ENTRYPOINT [ "java", "-jar", "/app/plantuml.jar" ]
```

<h2>Azure DevOps</h2><p>Nun können wir in Azure DevOps ein Repository, indem die Sourcen für Grafiken und Diagramme enthalten sein sollen, erstellen. In diesem Repo muss ein Ordner <code>plantuml</code> vorhanden sein. Nun gilt es eine Pipeline für dieses Repo zu erstellen, die bei Pushes in das Repo grundsätzlich alle <code>.puml</code>-Dateien im Ordner <code>plantuml</code> in das PNG-Format konvertiert. Im Anschluss werden die PNG-Dateien, nachdem diese in ein Standardverzeichnis für den Build verschoben wurden, als Artefakt mit Hilfe des UniversalPackages-Task als Package veröffentlicht. In Azure DevOps lassen sich Artefakte durch die Verwendung eines Package-Feeds inner- und auch außerhalb von Projekten wiederverwenden.</p>

```highlight
trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- script: docker run -v $(Build.Repository.LocalPath)/plantuml:/plantuml --rm -i codecentric/plantuml-docker:1.2021.16 plantuml/*.puml -w /plantuml -o ./output
  displayName: Export PlantUML diagrams

- task: CopyFiles@2
  displayName: 'Copy generated PNGs by PlantUML'
  inputs:
    SourceFolder: './plantuml/output'
    Contents: '*.png'
    TargetFolder: '$(Build.ArtifactStagingDirectory)'
 
- task: UniversalPackages@0
  displayName: 'Publish PlantUML images'
  inputs:
    command: publish
    publishDirectory: '$(Build.ArtifactStagingDirectory)'
    vstsFeedPublish: 'APIEnablement/PlantUML-Images'
    vstsFeedPackagePublish: 'plantuml-images'
    packagePublishDescription: 'PlantUML Images'
```

<p>Nun können wir die automatisiert erstellten PNG-Dateien mittels des Feeds in das Wiki Repository per <code>git</code> einchecken.</p>

```highlight
pool:
  vmImage: ubuntu-latest
 
steps:
- checkout: self
  persistCredentials: true
 
- task: CmdLine@2
  inputs:
    script:   git switch -c plantuml-images
- task: UniversalPackages@0
  displayName: 'Download PlantUML images'
  inputs:
    command: download
    downloadDirectory: '$(Build.SourcesDirectory)/plantuml-images'
    vstsFeed: '<NameofAzureDevOpsProject>/PlantUML-Images'
    vstsFeedPackage: 'plantuml-images'
    vstsPackageVersion: '*'
 
- task: CmdLine@2
  inputs:
    script: |
      git config --global user.email <user.email>
      git config --global user.name "<user.name>"
      git pull
      git add .
      git commit -m "added PNGs generated by PlantUML"
      git push --set-upstream origin plantuml-images
  displayName: Adding PNGs by using GIT
```

<p>Durch das Einchecken entsteht ein neuer Branch <code>plantuml-images</code>. Im Anschluss muss dieser per Pull-Request mit dem <code>main</code>-Branch gemerged werden. Dadurch können wir die PNG-Dateien innerhalb des Wiki unterstützt durch die Azure DevOps API (<code>https://dev.azure.com/<organisationName>/<projectId>/_apis/git/repositories/<area>/items?path=/plantuml-images/<image-name>.png</code>) und dem <code>img</code>-HTML-Tag einbinden.</p><h2>Zusammenfassung</h2><p>In diesem Blogpost haben wir nun einen Weg für eine Integration von PlantUML ins Azure DevOps Wiki gefunden. Auch wenn die Integration viel Wissen über Azure DevOps voraussetzt, ist es dennoch eine sehr einfache Lösung, die sich aber auch im Hinblick auf Verknüpfung von Build-Pipelines erweitern lässt.</p>

Projektdokumentation mit Azure DevOps – Diagramme

<p><span>Aktuell kocht mit Platform Engineering gerade ein Thema hoch, das in den Weiten des World Wide Web für viele Reaktionen sorgt. Gerade auch Kunden aus dem Enterprise-Umfeld führt es zu interessanten Nebeneffekten, wenn aus DevOps-Teams plötzlich Platform-Engineering-Teams werden. Ich möchte mit diesem Blogpost das Wording entmystifizieren und Möglichkeiten aufzeigen, die sich daraus ergeben.</span></p><p><span>Aber zuerst gehen wir ein paar Jahre in der Geschichte von codecentric zurück. Genauer gesagt, in das Jahr 2014. Zu dieser Zeit gab es die Idee der Agile Software Factory, die Teams befähigen sollte, die Idee eines Softwareprodukts schnell umsetzen zu können. Dazu zählt auch die Implementierung einer gesamten Toolchain zur Softwareentwicklung. Damit sprachen wir indirekt schon Themen wie Developer Experience und Governance an, ohne sie konkret zu benennen. Somit war in relativ kurzer Zeit die Lieferfähigkeit hergestellt, zumindest hinsichtlich eines ersten Inkrements. Wie gesagt, das war 2014!</span></p><p><span><span>Heutzutage haben wir es beim Software Development Lifecycle mit vielen Tools zu tun. Gerade in großen Unternehmen führt das zu einem Problem, da jede Abteilung ihre eigene Vorstellung hinsichtlich des Lebenszyklus der Software mitbringt. Folglich lohnt es sich, über eine Vereinheitlichung des Tool-Zoos nachzudenken. Das führt dazu, dass mehr und mehr die Idee entsteht, Entwickler mit Self-Service-Ansätzen zu unterstützen. Im Laufe der Zeit benötigen Unternehmen mehr Regeln und Richtlinien für die Entwicklung der Produkte oder gar einer Plattform. Genau das ist der erste Hebel, an dem Platform Engineering ansetzen möchte, in dem den Entwicklern in einem Unternehmen die Möglichkeit geboten wird, sich auf eingeschlagenen Pfaden oder entlang eines Golden Path zu bewegen, </span><span>um wieder das Ursprüngliche der Softwareentwicklung zu fokussieren – Ideen schnell lauffähig umzusetzen</span><span>.</span></span></p><h2><span>Golden Path?</span></h2><p><span>Die Schritte in Richtung Golden Path hat Spotify auch im Jahr 2014 unternommen. Hier zeigt sich, dass codecentric mit der Idee der Agile Software Factory auf der Höhe der Zeit war,das ganze Thema aber noch nicht zu einem Begriff zusammenfassen konnte. Man vermutet, dass Spotify den Begriff </span><i><span>Golden Path</span></i><span> der Dune-Trilogie entlehnt hat. Nach der Erklärung des </span><a href="https://dune.fandom.com/wiki/Golden_Path"><span>Dune Fandom</span></a> <span> stellt der </span><i><span>Golden Path</span></i><span> einen optimalen Weg durch die zahllosen Fäden von Ursache und Wirkung dar, denen die Menschheit begegnet ist. Dieser optimale Weg war das, was man im Zeichen von Wachstum in der damaligen Zeit bei Spotify erreichen wollte, um bei der Entwicklung von Softwarekomponenten keine Geschwindigkeit zu verlieren. Aber es geht nicht darum, einen Entwicklern zu gängeln oder Standards durchzusetzen. Vielmehr sollten Teams das Rad nicht neu erfinden und auch weniger Entscheidungen treffen müssen. Unter diesem Gesichtspunkt sollten Unternehmen Plattformangebote auch aufsetzen: als sichtbare und spürbare Unterstützung für Entwickler.</span></p><p><span>Somit wird die Idee des</span><i><span> Golden Path</span></i><span> nicht nur auf CI/CD-Prozesse beschränkt, sondern hat im Sinne von Platform Engineering die ganze Kette von Deployment-Prozessen im Blick, wie </span></p><p><span>– Hinzufügen von Umgebungsvariablen und Ändern von Konfigurationen</span></p><p><span>– Hinzufügen von Services und Abhängigkeiten</span></p><p><span>– Rollback und Fehlersuche </span></p><p><span>– Eine neue Umgebung aufsetzen</span></p><p><span>– Hinzufügen/Ändern von Ressourcen</span></p><p><span>– Rollenbasierte Zugriffskontrolle umsetzen</span></p><p><span>Hierbei steht aber immer der Self-Service-Aspekt im Vordergrund. Das führt zu einer Internal Developer Platform, die nach </span><a href="https://martinfowler.com/articles/talk-about-platforms.html"><span>Evan Bottcher</span></a> <span> „eine Grundlage von Self-Service-APIs, Tools, Services, Wissen und Support“ darstellt. Eine solche Plattform ist ein entsprechender zweiter Hebel von Platform Engineering, den mittlerweile einige Hersteller bedienen. </span></p><p><span>Ein Blick in die Tool-Landschaft rund um Platform Engineering zeigt, dass zwei Produkte aktuell im Markt sehr präsent sind: </span><a href="http://backstage.io/"><span>Backstage</span></a> <span> und</span> <a href="https://humanitec.com/"><span>Humanitec</span></a> <span>. Mein Kollege Jonas hat in </span><a href="https://blog.codecentric.de/en/2022/07/crossplane/"><span>seinem letzten Blogpost mit Crossplane</span></a> <span> noch ein weiteres Tool vorgestellt, das ich in diesem Post nicht näher beleuchte.</span></p><h2><span>Backstage</span></h2><p><span>Spotify hat Backstage entwickelt und dem Markt als Open-Source-Produkt zur Verfügung gestellt. Frei nach meinem Kollegen Pascal Sochacki gilt es aber Backstage mehr als Framework zu verstehen, mit dem Unternehmen in die Lage versetzt werden, ein Frontend für die interne Entwicklungsplattform zu liefern. Hierzu bietet Backstage die Möglichkeit, Softwarekomponenten durch Software-Templates bereitzustellen. Das bedeutet im konkreten Fall, dass ein Git-Repo inkl. Docker- und Pipelinefile erstellt wird. Nach erfolgreichen Deployment wird die Komponente dann im Anschluss in Backstage gelistet. Daneben lässt sich das Framework durch Plugins, um weitere Funktionalitäten auch hinsichtlich der Sichtbarkeit auf das Deployment erweitern.</span></p><h2><span>Humanitec</span></h2><p><span>Humanitec versteht sich im Vergleich zu Backstage als Plattform-Orchestrator und somit als zentrale Einheit einer Internal Developer Platform. Es stellt die Grundlage für ein dynamisches Konfigurationsmanagement dar, das vom Hersteller als Declarative Application Model beschrieben wird. Dieses Modell beschreibt hierbei den Workload eines Deployments möglichst agnostisch. Eine Grundlage für diese Art der Beschreibung entsteht gerade mit der Platform-Agnostic Workload Specification (</span><a href="https://paws.sh/"><span>PAWS</span></a> <span>). </span></p><p><span>Mit Backstage, Humanitec und Crossplane sehen wir nun Tools. Ihre Wirksamkeit beschränkt sich zum einen auf die Sichtbarkeit und zum anderen auf die Deployment-Orchestrierung von Services. Aber genau diese zwei Punkte sollen innerhalb der Arbeit eines Entwicklers automatisiert werden und auch die Automatisierung soll auf einfache Weise erfolgen. Somit weisen diese genannten Tools stellvertretend einen Weg zu einer Internal Developer Platform, die die häufig angesprochene Developer Experience gewährleisten kann.</span></p><h2><span>Fazit</span></h2><p><span>Platform Engineering ist somit keine wirklich neue Idee, sondern es  sollen die Prozesse rund um CI/CD bei der Entwicklung von Software End-2-End betrachtet werden. Ebenso geht es auch darum, eine Art Einheitlichkeit im Bezug auf die Tool-Landschaft, die Komponenten und deren entsprechende Nutzung zu erzeugen. Das setzt auch die Kommunikation zwischen einzelnen Personen und Teams voraus. </span></p><p><span>Lasst uns gerne darüber diskutieren. Was ist euer Verständnis von Platform Engineering? Was macht ihr vielleicht schon? Was wollt ihr gerne auf eure Situation adaptieren?</span></p><p> </p>

Platform Engineering – Eine Einordnung

Warum „Platform Engineering“ eigentlich der falsche Begriff ist und wie man den Golden Path findet, erklärt Daniel Kocot, Senior Solution Architect, im folgenden Interview.\nMarco Paga: Warum ist Platform Engineering interessant?\nDaniel Kocot\n: Ich habe im September [2022] einen ersten Versuch eines \nBlogposts\n gestartet, um das Thema aufzunehmen und zu verstehen, woher der Drive kommt, um festzustellen, dass wir das bei codecentric seit 2014 gemacht haben, ohne es „Platform Engineering“ zu nennen. Wir haben schon immer etwas ausgeliefert oder zu Kunden mitgebracht, um sie zu befähigen, Softwareprodukte schneller umzusetzen. Das heißt, es ist alles schon da gewesen, jetzt gibt es einen Begriff dafür – der vielleicht nicht ganz passend ist, das schon vorab.\nMaximilian Mayer: Lass uns den Begriff „Platform Engineering“ gleich vorab klar definieren, damit jeder von uns versteht, was das überhaupt ist, wenn wir darüber sprechen.\nDK\n: Platform Engineering ist eigentlich ein falscher Begriff. Ich baue keine Plattform auf, sondern unterstütze dabei, eine Plattform entstehen zu lassen. Also Softwareprodukte oder ein Softwareprodukt an sich. Das heißt, ich bin in der DevOps-Schiene unterwegs und versuche entsprechend, all das, was diese Software braucht, in den Lebenszyklus zu integrieren. Darin steckt auch Governance: dass man Vorgaben macht und schaut, wohin die Reise gehen könnte. Ich möchte damit verhindern, dass Teams etwas benutzen, was im Unternehmen nicht gesetzt ist, und baue Schranken auf. Wenn wir über Platform Engineering reden, dann auch über den „Golden Path“ und welche Rolle Spotify darin hat.\nMM: Wir reden also nicht von einzelnen CI/CD-Pipelines, sondern Platform Engineering ist eher so etwas wie ein Meta-Begriff.\nDK\n: Genau. Es ist ein Überbegriff. Vielleicht möchte ich auch nicht, dass eine Plattform das für mich erledigt, sondern eine Art von Orchestrierung und eine unendliche Anzahl von verschiedenen Plattformen, die mir helfen, Dinge voranzutreiben. Es kommt auch darauf an, wo ich unterwegs bin. Falls ich mit Azure arbeite, ist es eventuell sinnvoll, gewisse Sachen mit Azure DevOps zu lösen. Aber ich kann es durch Platform Engineering so abstrahieren, dass die Software-Entwicklungsteams gar nicht mitbekommen, welche darunter liegenden Technologien sie benutzen. Ganz klar spielt hier auch Developer Experience eine Rolle: das Gefühl zu haben, sich auf die Entwicklung konzentrieren zu können, ohne z. B. irgendwelche Pipelines bauen zu müssen. Es ist alles schon da.\nMP: Das heißt, es ist zum einen Dokumentation, also es sind Hilfestellungen oder Ideen hinterlegt, wie bestimmte Dinge umgesetzt werden, welche Technologien oder innerhalb welchen Technologiespektrums man sich bedienen sollte. Und ich habe auch schon Artefakte mitgebracht, z. B. ein Testing oder etwas in Richtung CI/CD. Das ist ein Baukasten, aus dem ich mich bediene. Fehlt außerdem noch etwas?\nDK\n: Es ist, grob gesagt, genau dieser Baukasten. Was wichtig ist: Ich muss die Entwickler abholen und mich erkundigen, was sie benutzen, was „State of the Art“ ist. Vielleicht stelle ich z. B. fest, dass eine bestimmte Frontend Library nicht das Richtige ist. Ich muss einen Weg finden, die Dinge langfristig besser steuern zu können. Das trägt Spotify sehr stark nach außen, mit Backstage z. B. Die Grundlage von allem ist der sogenannte „Golden Path“: den Fokus auf die reine Entwicklung zu legen. Wir haben, wie ihr auch wisst, sehr häufig Debatten über CI/CD-Pipelines, welches Tooling, warum und zu welcher Zeit. Das will man umgehen, indem man sagt: OK, du willst eine Spring-Boot-Anwendung entwickeln – hier ist ein Button, der ganz viele Dinge auslöst. Schon passieren Sachen im Hintergrund, und ich kann mich wieder auf die Entwicklung fokussieren. D. h. ich kann das Repo auschecken und direkt anfangen, ohne mir Gedanken machen zu müssen, was ich ja auch nicht will. Ich will mir nicht zuerst etwas aufbauen, sondern direkt starten. Es ist alles gesetzt, es gibt vielleicht gewisse Spielregeln, an die ich mich halten muss. Die kann ich auch noch verändern. Aber es ist ein Baukasten, plus ein bisschen mehr.\n„Was wir hier tun, ist nichts Neues. Wir geben dem Ganzen einen anderen Raum und eine andere Position.“\nMM: Das gibt es in der IT doch eigentlich seit 20, 30 Jahren und es hat jetzt einfach einen neuen Namen bekommen – oder sehe ich das grundlegend falsch? Ich komme aus dem Ops-Bereich, dort wurde den Entwicklern häufig schon vorgearbeitet: „Schubs deine Sachen da hinein, dann verteilen wir es weiter“ usw., d. h. sie hatten schon früher in mehr oder weniger komfortablen Konstrukten schöne Buttons, auf die sie nur noch klicken oder E-Mails, die sie verschicken mussten, um Sachen über den Zaun zu werfen. Sehe ich das verkehrt?\nDK\n: Die Grundlage ist immer schon da gewesen. Was wir hier tun, ist nichts Neues. Wir geben dem Ganzen einen anderen Raum und eine andere Position. Wir wollen den gesamten Entwicklungszyklus transparent unterstützen und bieten dir ein gewisses Set von Möglichkeiten. Du kannst natürlich auch den Golden Path verlassen und sagen: Juckt mich alles nicht. Aber wenn du in einem Großunternehmen gewisse Regularien hast und bestimmte Software- und Infrastrukturkomponenten nutzen möchtest, hast du hiermit eine gewisse Chance, alles in eine Art von Alignment zu setzen, sodass alle das nutzen, was da ist und kein Wildwuchs entsteht. Denn das sehen wir bei sehr vielen Kunden: Sehr, sehr viele Komponenten, aber man fragt sich, in welchen Komponenten das Service-Team, das für die Bereitstellung zuständig ist, eigentlich fit ist. Man muss sich um eine schnellere Time-to-Market bemühen. Und am meisten halten Diskussionen darüber auf, \nwas\n man verwendet und \nwarum\n. Es gibt auch Sicherheit, wenn alles standardisiert ist und es geht dann nur noch um die Entwicklung: das Erstellen und Deployment von Software.\nDer Golden Path\nMP: Kannst du den Begriff „Golden Path“ noch einmal für uns einordnen und sagen, was sich dahinter verbirgt?\nDK\n: „Golden Path“ ist das, was die Geschwindigkeit bei Spotify ausmacht. Die können relativ schnell Sachen ausliefern, die bekommen ein schnelles Onboarding hin. Der Golden Path zielt darauf ab, gewisse Sachen zu standardisieren: Abhängigkeiten von Services, Discovery von Services etc., sodass ich Sachen nicht nur schnell finde, sondern auch schnell nach dem Baukastenprinzip zusammenklicken und mich aufs Entwickeln fokussieren kann. \n„Man muss sich um eine schnellere Time-to-Market bemühen. Und am meisten halten Diskussionen darüber auf, \nwas\n man verwendet und \nwarum\n.“\nMM: Das Gedanke hinter dem Golden Path ist also „Schuster, bleib bei deinen Leisten“ bzw. „Entwickler, kümmere dich bitte darum, dass du entwickelst und nicht um das Drumherum“, denn Letzteres wird schon vorbereitet. Spannend, dass du Standardisierung nennst, denn daran scheitert es oft in Unternehmen: Man möchte oft den zweiten Schritt vor dem ersten machen – Kubernetes und all die fancy Sachen – aber der erste Schritt, Dinge zu standardisieren, wird vergessen. So entsteht Schatten-IT: Leute, die die neuesten Sachen machen wollen, treffen auf solche aus dem „Legacy“-Bereich, die noch nicht abgeholt sind und beim Bewährten bleiben wollen. Mit Platform Engineering lassen sich alle schön einfangen, um einen Rahmen zu geben, oder?\nDK\n: Platform Engineering ist eine Art von Knowledge Sharing: Ich teile das Wissen, das ich im Unternehmen gesammelt habe, wie ich Dinge aufbaue. Marco nannte es vorhin „Dokumentation“.  Für Entwickler ist es dann alles unter einem Dach, und ich muss nur dafür Sorge tragen, dass die Entwickler es benutzen. Natürlich gibt es Feedback Loops. Was man mit Platform Engineering erreichen möchte, ist eine Art Self-Service.\nMP: Self-Service heißt, es ist noch kein Platform Engineering, wenn man ein gutes Confluence-Wiki pflegt und ein Ticket-System hat, wo man bestimmte Dinge anfragen kann. Da geht es schon um mehr.\nDK\n: Ja. Ich mag den Begriff „Developer Experience“ nicht – das ist immer so eine eine platzende Seifenblase, und kein Mensch kann etwas damit anfangen – aber es geht darum, dass der Entwickler sagen kann: „Ich klicke mir etwas zusammen, dann passiert etwas Magisches. Ich muss nicht wissen, wie ein Kubernetes-Deployment funktioniert, weil es gar nicht meine Baustelle ist. Ich will nur sehen, dass mein Service in irgendeinem Cluster liegt und funktioniert.“\nMM: Ich war jahrelang im Ops-Bereich tätig und kenne den ewigen Konflikt mit Entwickler-Teams, die mal etwas anderes machen wollen. Wenn man denen dann sagt: Nimm das und benutze es, wird es immer welche geben, die ihre eigenen Tools benutzen wollen, das neueste JavaScript-Framework usw. Hier sehe ich die Gefahr, dass sich Geschichte wiederholen könnte. Wie gehe ich damit um?\n„Platform Engineering ist eine Art von Knowledge Sharing: Ich teile das Wissen, das ich im Unternehmen gesammelt habe, wie ich Dinge aufbaue.“ \nDK:\n Gute Frage. Man muss den Mehrwert erklären können: Warum gehen wir so vor? Weil wir Geschwindigkeit wollen. Wenn das der eine oder andere als Gängelung auffassen sollte, kann man sagen: Ja, du kannst das anders machen, aber dann bekommst du keine Unterstützung und wir können das nicht jedes Mal machen. Wir können nicht auf jede Technologie reagieren, weil wir einen Plan haben. Wenn jemand Vorschläge hat, kann er die natürlich einbringen. Das ist dann allerdings ein Abweichen vom Golden Path, vom „One-Click Shop“, wie es ein Kunde von mir nennt. Ich mache einen Klick und bin schon in der Entwicklung. Ich kenne genug Beispiele von Kunden, wo das schon so funktioniert: Das nennt sich dann „App Store“ o. ä., wo du dir wirklich mit einem Klick Applikationen in jeder Programmiersprache zusammenbauen lassen kannst. Und alles ist konfiguriert. Das ist möglich. Es ist nur die Frage, wie schnell ich das auf die Mannschaft übertragen kann. \nEs geht auch um Adaption, nicht um Kopieren. Nur weil Spotify es so macht und Backstage nutzt, heißt es nicht, dass wir es auch so machen. Es geht darum, zu entscheiden, was mir aktuell hilft – und wenn es erstmal nur ein Git-Repo ist.\nMP: Diese Einordnung ist wichtig. Es ist ein Weg, den man geht, und je nachdem, wo man startet, kann man relativ schnell Mehrwert bieten. Während des Prozesses lassen sich ja auch Schleifen drehen. Wenn Leute andere Technologien verwenden wollen, die z. B. schneller oder besser machen, kann man diesen Leuten Anknüpfungspunkte bieten – sei es, dass man sich in einer Gilde austauscht oder in Sachen Architektur die Möglichkeit hat, einen Dialog aufzubauen oder das Ganze auszutesten, zu validieren, ob das wirklich mehr bringt, dass es irgendwo geregelt ist, und die Potentiale mitnehmen kann.\nDK\n: An Begrifflichkeiten gibt es auch noch „Internal Developer Platform“, abgekürzt IDP, was total schlecht gewählt ist, weil IDP normalerweise etwas anderes bedeutet. Max hat es schon gesagt: Es gibt tausend Begriffe für Dinge, die eigentlich schon da sind. Man muss für sich schauen, was das Ziel ist, welcher Player im Markt man ist: Bin ich ein Datenlieferant, muss ich natürlich bis zum Ende durchautomatisieren, und das muss ich in eine Plattform – jetzt sage ich es schon wieder – oder einen Lebenszyklus gießen. Das ist es, was wir als Entwickler tun: Wir haben eine Idee, setzen diese um, indem wir etwas entwickeln, wir testen, kommunizieren viel, holen Feedback. Und am Ende gibt es ein Artefakt, das in eine Produktion deployt wird. Was wir [mit Platform Engineering] leisten, ist einfach eine Art Unterstützung. Wir helfen, Sichtbarkeit zu erlangen, Dinge zu sehen und zu verstehen, das Suchen und Finden für Entwickler noch einfacher zu machen – in der Regel braucht man einfach eine Such-Engine, die einem hilft, Dinge wiederzufinden. Wir bauen nichts Neues, sondern nehmen Komponenten, die seit 20 Jahren oder länger schon da sind – und geben ihnen ein neues Ansinnen. \nMM: Es ist also weniger die Frage, \nwomit\n als die Frage, \nwie \nman es macht. Hier sehe ich zwei Kernelemente: Standardisierung und Integration der Möglichkeiten. Oft hat man eine Build-Pipeline und einen Kommunikationskanal an anderer Stelle. Wenn man das miteinander sauber integrieren kann, ist das schon die halbe Miete. Wenn man dann noch klar macht, dass es das ist, was mit dem Label „Platform Engineering“ gemeint ist, hat man den Begriff schon entmystifiziert.\n„Es geht um Adaption, nicht um Kopieren. Nur weil Spotify es so macht und Backstage nutzt, heißt es nicht, dass wir es auch so machen.“\nTool-Unterstützung\nMP: Was wirklich wichtig ist, ist, dass man nicht einfach irgendein Tool kauft und installiert. Sondern es geht um viel mehr.\nTrotz allem gibt es Tools, die unterstützen. Was sind sonst noch Tools, die man nutzen kann?\nDK\n: Backstage ist eine Art Entwicklungsportal oder -Framework. Es kommt darauf an, was man braucht. Es gibt auch Humanitec, das so etwas wie Plattform-Orchestrierung bietet, eine zentrale Steuerungseinheit. So werden Dinge einfacher und greifbarer, weil wir nicht so viel über die darunter liegende Plattform wissen müssen, sondern einfach eine Art Konfigurationsmanagement machen. Bei Humanitec gibt es auch eine Beschreibungssprache, die sich \nPlaform-Agnostic Workload Specification \nnennt. Die beschreibt, wie ein Workload Plattform-agnostisch aussehen soll. Das heißt, ich kann mir in einer YAML-Datei den Workload beschreiben, den ich auf verschiedene Plattformen auslagern möchte. Jonas hat über \nCrossplane\n geschrieben, das auch in diese Richtung geht: Es bietet Möglichkeiten für verschiedene Cloud-Hersteller, bewegt sich also in Richtung Multi-Cloud, und kann Dinge dadurch vereinfachen. Es gibt, wie immer, einen Haufen Tools, und man muss sich für sich überlegen: Was will ich eigentlich erreichen bzw. was hilft mir im Moment? Aktuell brauchen die meisten eine Sichtbarkeit auf vorhandene Services und darauf, wie eigentlich entwickelt wird, was die eigenen Standards sind. Daraus ergeben sich im Laufe der Zeit weitere Tools, die ich brauche, um den Platform-Engineering-Begriff füllen zu können. Das Erste ist für die meisten Discovery. Das ist ein einfaches und lösbares Problem: Sichtbarkeit auf das, was ich habe und wo ich stehe.\nMP: Vielen Dank, Daniel, dass du dir die Zeit genommen hast, mit uns das Thema Platform Engineering mit Leben zu füllen und den Leuten näher zu bringen!\nDieses Gespräch führten Max, Marco und Daniel im Rahmen unseres Podcasts SoftwerkerCast. Weitere Folgen unter \nhttps://www.codecentric.de/softwerkercast\n. \n\nMaximilian Mayer\n arbeitet als APM Consultant für die codecentric AG. Er hat viele Erfahrungen als Linux-Admin und im DevOps-Umfeld gesammelt. Neben Automatisierung interessiert er sich für Ruby-Entwicklung. Motorräder und alte Autos zählen zu seinen Leidenschaften.\nMarco Paga\n entwickelt Software aus Leidenschaft. Gerne arbeitet er im Team an der Lösung komplexer Probleme. In der Vergangenheit hat er dabei erfolgreich Legacy-Applikationen modernisiert, um diese auf geänderte Herausforderungen vorzubereiten. Alle Beteiligten auf diesem Weg mitzunehmen und für neue Technologien zu begeistern – das ist für ihn selbstverständlich.

„Platform Engineering ist eine Art von Knowledge Sharing“

<p>In software development, one question that constantly arises is how the current project can be comprehensively documented. The most common way to do this is to use Confluence or some other wiki. But why not use the code itself?<br /> This is why, in the first part of this article series, I will give you an understanding of <a href="http://jbake.org/" target="_blank">JBake</a> .<br /> JBake is actually a generator for static websites. Dan Allen, Project Lead of the Asciidoctor project, calls it “Jekyll of the JVM”. Using plugins for Maven and Gradle, JBake can easily be integrated into build pipelines.<br /> I will start off by explaining potential use cases of JBake based on an example. First and foremost, we will build a simple Gradle project to provide a starting point for further steps.</p>

```
group 'de.codecentric.dk.afgd'
version '1.0-SNAPSHOT'

apply plugin: 'groovy'
apply plugin: 'java'

sourceCompatibility = 1.8

repositories { 
   mavenCentral()
   jcenter()
}

dependencies {
   compile 'org.codehaus.groovy:groovy-all:2.3.11'
   testCompile group: 'junit', name: 'junit',version: '4.12'
}

```

<p>Now we extend the build file by the plugin <em>jbake-gradle-plugin</em>.</p>

```
plugins {
     id 'org.jbake.site' version '1.0.0'
}

```

<p>This gives us another “bake” task that allows us to “bake” the documentation. For this, we also need a JBake basic installation within the sources. Under MacOS, this can be easily done with SDKMAN</p>

```
$ sdk install jbake
```

<p>or Homebrew</p>

```
$ brew install jbake
```

<p>By default, the Gradle plugin expects the documentation sources to be located in src/jbake. By using parameters in the build file, the source and destination can be adjusted. The target, however, is always located in the build folder. For our example, we use the following values:</p>

```
jbake {
     srcDirName = 'src/documentation'
     destDirName = 'documentation'
}

```

<p>Since JBake is now installed, we can run the command</p>

```
jbake -i
```

<p>in the folder</p>

```
src/documentation
```

<p>The resulting structure can now be extended and adapted as desired. Content can be saved in the content folder in the form of HTML, Asciidoctor, or Markdown files. For this blog article, we will replace the existing file about.html with about.adoc and adjust the content accordingly.</p>

```
= Project documentation
Daniel Kocot
2017-10-03
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

```

<p>Within the Asciidoctor document, it is possible to save JBake metadata such as page type, tags, and the status of each page. The latter controls the visibility of the pages after the “baking process”. If you do not like the standard template, you can customize it according to your own preferences using the template languages Freemaker, Groovy Simple, Groovy Markup, Thymeleaf, and Jade.<br /> Now, looking back at the build process, we can connect the build task with the bake task to complete this first part.</p>

```
build.dependsOn bake
```

<p>If we now execute the build task, the documentation will be generated as well. In the second part, we will add more ingredients to our agile, freshly baked documentation.</p><p>Check out the demo in my Git Repository: <a href="https://gitlab.com/danielkocot/agile-fresh-baked-docs">agile-fresh-baked-docs</a> .</p>

Agile, oven-fresh documentation. Part 1: JBake

<p>After looking at the configuration of JBake in the <a href="https://blog.codecentric.de/en/2018/02/agile-oven-fresh-documentation-part-1-jbake/">first part</a> , I will now extend the scenario described in the previous post by adding PlantUML. PlantUML makes it possible to describe UML diagrams in simple textual notation.</p><table><tbody><tr><td>

```
@startuml
start
:Hello world;
stop
@enduml

```

</td><td><img src="https://media.graphassets.com/lMPuOCPQ9Ku40co6J1DC" alt="Result of " /></td></tr></tbody></table><p>First of all, we will integrate PlantUML into the existing Gradle build file. In order to do so, we need asciidoctorj-diagram as an external library for the build script. With the upcoming release of the Gradle plugin it is no longer necessary. The configuration of JBake needs to be adjusted so that the asciidoctorj-diagram library can be used. The asciidoctorj-diagram library now allows us to use PlantUML diagrams within the Asciidoctor document.</p>

```
buildscript {
    repositories {
        mavenCentral()
        jcenter()
    }
 
    dependencies {
        classpath 'org.asciidoctor:asciidoctorj-diagram:1.5.4.1'
    }
}
 
plugins {
     id 'org.jbake.site' version '1.0.0'
}
 
group 'de.codecentric.dk.afgd'
version '1.0-SNAPSHOT'
 
apply plugin: 'groovy'
apply plugin: 'java'
 
sourceCompatibility = 1.8
 
repositories {
    mavenCentral()
    jcenter()
}
 
dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.3.11'
    testCompile group: 'junit', name: 'junit', version: '4.12'
}
 
jbake {
    srcDirName = 'src/documentation'
    destDirName = 'documentation'
    configuration['asciidoctor.option.requires'] = "asciidoctor-diagram"
    configuration['asciidoctor.attributes'] = [
            "sourceDir=${projectDir}",
            "imagesDir=diagrams",
            "imagesoutdir=${bake.input}/assets/diagrams"
    ]
}

build.dependsOn bake

```

<p>We now create a new file, architecture.adoc, within the content folder. The following code block shows the content of the file.</p>

```
= Architecture documentation
Daniel Kocot
2017-11-20
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

== First draft

[plantuml, "first_draft", "png"]
----
node "Confluence as content repository" as nodeconf
folder Intranet{
    together {
        node "WordPress Node 1" as nodeiwp1
        node "WordPress Node 2" as nodeiwp2
        node "WordPress Node 3" as nodeiwp3
        node "WordPress Node 4" as nodeiwp4
    }
}
folder Extranet{
    together {
        node "WordPress Node 1" as nodeewp1
        node "WordPress Node 2" as nodeewp2
        node "WordPress Node 3" as nodeewp3
        node "WordPress Node 4" as nodeewp4
    }
}
node "LoadBalancer / nginx Intranet" as lbinginx
node "LoadBalancer / nginx Extranet" as lbenginx
node "Content Delivery Network" as cdn
cloud "Intranet" as intranet
cloud "Extra/Internet" as internet
actor "Internal User" as internal
actor "External User" as external
nodeconf --> nodeiwp1
nodeconf --> nodeiwp2
nodeconf --> nodeiwp3
nodeconf --> nodeiwp4
nodeconf --> nodeewp1
nodeconf --> nodeewp2
nodeconf --> nodeewp3
nodeconf --> nodeewp4
nodeewp1 <--> lbenginx
nodeewp2 <--> lbenginx
nodeewp3 <--> lbenginx
nodeewp4 <--> lbenginx
nodeiwp1 <--> lbinginx
nodeiwp2 <--> lbinginx
nodeiwp3 <--> lbinginx
nodeiwp4 <--> lbinginx
cdn <--> nodeconf
cdn --> nodeewp1
cdn --> nodeewp2
cdn --> nodeewp3
cdn --> nodeewp4
cdn --> nodeiwp1
cdn --> nodeiwp2
cdn --> nodeiwp3
cdn --> nodeiwp4
lbinginx <--> intranet
lbenginx <--> internet
external <--> internet
internal <--> intranet
----

```

<p>After writing the first draft of our architectural diagram into the document, there is still the question of how the text content is turned into a graphic.</p><p>For this purpose, when creating the entire documentation, the first thing we do is generate a picture – in our case a PNG file – via PlantUML. This picture is saved in the assets folder under the file name first-draft with the file extension .png. In a second step, JBake will then create the corresponding HTML file based on the Asciidoctor file.</p><p>The PlantUML integration enables us to also maintain the important architecture diagrams in close alignment with the source code.</p><p>In the third part of this series, we will take a look at test reports and their integration in JBake.</p><p>Check out the demo in my Git Repository: <a href="https://gitlab.com/danielkocot/agile-fresh-baked-docs">agile-fresh-baked-docs</a> </p>

Agile, oven-fresh documentation. Part 2: PlantUML with JBake

<p>In the first two parts of this blog series, I introduced <a href="https://blog.codecentric.de/en/2018/02/agile-oven-fresh-documentation-part-1-jbake/">JBake</a>  and discussed the integration of <a href="https://blog.codecentric.de/en/2018/03/agile-oven-fresh-documentation-part-2-plantuml-jbake/">PlantUML</a> . In this post, I will move on to test automation and documentation, integrating Spock into the existing stack as a test framework.</p><h2>What is Spock? And why another test framework?</h2><p>Spock is written in the JVM language Groovy and uses its own Domain-Specific Language (DSL) to describe the tests. Thanks to this DSL, the tests are clearly structured and readable. Needless to say, it is also possible to execute pure Java code with Spock.<br /> What’s also special about Spock is the way it displays failed tests, visualizing the failed condition down to its individual components.</p><h2>From requirement to test to “tested” documentation</h2><p>Every test in software development emerges from a specific requirement. Typically, these requirements are kept in a wiki. Now, how can the developer react to direct changes in a requirement within a sprint? Can requirements be mapped “as code” even by Product Owners who do not have any development background?<br /> To reach this objective, we use Gherkin, a so-called “Business Readable DSL”. Gherkin is a line-oriented language that uses indentation to define structure.</p><p></p><p>Using a self-written Gradle task, the individual Gherkin specifications can now be transformed into Spock specifications. For this post, the Gradle task only includes the transformation of the simplest Gherkin structure.</p><p></p><p>The Groovy script is the first basic implementation of the Gherkin specification. Thanks to Gherkin, we can now implement a workflow between the product owner and the developers, which in turn can help reduce iterations between a requirement and its implementation within a sprint.</p><p>Now if, because of the transformed requirements, the developer chooses to pursue test-driven development using Spock, it is worth wondering how we can map the results with JBake. For this purpose, we will use Spock Reports.</p><p>Spock Reports offers the option to display the results of the Spock test in AsciiDoc, using templates. To adjust these templates, we need to create a <em>properties</em> file under <em>test/resources</em>.</p><p></p><p>In JBake v2.6 it is now possible to exclude files from the documentation generation process using <em>.jbakeignore</em>. We now use this feature to create the test reports, since they are integrated via include. However, we do not want these included files to be separate HTML files; rather, their contents should simply be pasted into the index.html. To make this part of the continuous process, we need to create a Gradle task to generate the ignore file.</p><p></p><p>This task will now be executed after the Gradle Test task, which we will achieve by using <em>test.finalizedBy(createjbakeignorefile)</em>.</p><p>Triggered by the test task within the Gradle build, the report is written directly into the source directory of the documentation, and the <em>build.finalizedBy(bake)</em> entry creates the documentation with JBake at the end of the build.<br /> In this way, the tested requirements become an integral part of the documentation.</p>

Agile, oven-fresh documentation. Part 3: Tested requirements with JBake

<p>In a recent blog post, Benjamin Wilms gave an introduction to “<a href="https://blog.codecentric.de/en/2018/07/chaos-engineering/" target="_blank">Chaos Engineering</a> “. But how to apply potential Chaos Engineering experiments and their results in a specific company context?</p><p>I would like to introduce the Chaos Engineering GameDay as a platform for this purpose. The idea behind it is that we learn how to “survive” a production outage in a secure environment (in terms of space and time). A GameDay is basically a fire drill. As with any drill, the first question is what to practice. Do we want the database system to fail? Or rather a major component of the system?</p><p>To get an impression of how a GameDay works, the initial radius of the experiment should be very limited. It is also advisable to start by trying out the GameDay within a test environment. After that, you should be all set for a proper GameDay in production, so you can start planning it from beginning to end.</p><p>The most important thing when carrying out Chaos Engineering GameDay is communication. First, we set up a Command Center. This can be either a virtual chat or a conference room. It is important that everyone in this room is provided with insights into success, termination criteria and any other overviews relevant to GameDay. This is the only way to ensure that potential sources of error are discovered quickly. If something goes wrong, participants should always have a recovery plan and a set of criteria at hand.</p><p>Before we delve into GameDay details, here is a recap of the rules of Chaos Engineering, as already cited by <a href="https://blog.codecentric.de/en/2018/07/chaos-engineering/" target="_blank">Benjamin Wilms</a> :</p><ol><li>Talk to your colleagues about the planned chaos experiments in advance!</li><li>If you know your chaos experiment will fail, don’t do it!</li><li>Chaos shouldn’t come as a surprise, your aim is to prove the hypothesis.</li><li>Chaos Engineering helps you understand your distributed systems better.</li><li>Limit the blast radius of your chaos experiments.</li><li>Always be in control of the situation during the chaos experiment!</li></ol><h2>A more detailed look at Chaos Engineering GameDay</h2><p>A GameDay lasts between two and four hours. Ideally, in addition to developers and operations, the “customers” behind the application should also participate in the planned event. But what else needs to be prepared apart from the actual experiment?</p><p>Every GameDay needs a clear goal to which the experiment can be applied. The participants then define their roles based on this goal, i.e. based on how much they identify with it. It’s up to them if they want to be participate or not – everyone can decide for themselves. In addition to the defined goal, it is important to prove the hypothesis with test cases.<br /> But before we define our objective, we should do two things. After opening GameDay, we spend a little time on doing a presentation of the current system architecture, preferably on a whiteboard in the center of the room. This should, above all, ensure that all participants keep the current status of the system in mind as they make further considerations.</p><p>Next, the group tries to come up with potential test cases. For some tests, it might be crucial not to look at the actual time. We already know from experience that some applications do not run into errors within a certain time interval. Particularly if the tests are run in production, it is important to define a criterion.</p><p>The tests are now defined, so we can get started. While we run the test, some questions arise. If these can be answered adequately, we continue with the next test. Here are some examples:</p><ul><li><i>Do we have enough information?</i></li><li><i>Did we expect exactly this behavior?</i></li><li><i>What does the customer see while this happens?</i></li><li><i>What happens right before and after the component under consideration?</i></li></ul><p>As soon as all the tests have been completed, we can briefly sum up results. This summary is also a conclusion of the GameDay, though it can be contemplated for a few more days in order to to allow everyone involved to take a deeper look at the test events and results with some distance. It is best to initially focus on the most striking tests and corresponding results. Following the discussion, the detected errors are passed via a ticket system to the right people for clarification and fixing. However, all other tests should also be looked at more thoroughly, e.g. to find out if anything negative has been noticed before. It is also worth considering whether these positive tests can be automated in any way to protect future releases against regression.</p><p>To conclude: while a single GameDay can already provide some insights into the behavior of an application or component, continuous implementation will help increase security in the operation of distributed applications and components in the long run. If you like the idea of ​​Chaos Engineering GameDays, you can get started even without having an experiment at hand. Often enough, it is sufficient to get the right people to be in the same room together and start asking questions. Ensuing discussions and reflections will already give rise to quite a few significant insights at this early stage.</p><p>I hope this blog post could give you a first glimpse into planning a Chaos Engineering GameDay. If you have any questions, suggestions and maybe wishes related to the field of Chaos Engineering, feel free to drop a comment.</p>

For quite some time now, the topic “API as a Product” has been appearing in various media. But what does it actually mean?
If you look at APIs, the focus is often on the technical implementation, whereas the view of the business is neglected. Increasingly, however, more and more offerings are being created precisely in this context. So we should start to understand APIs as more than just a product. Today we use them as a service to give a user the possibility to access core resources of a business with low risk and costs. In this respect, we should also see an API less as a pure code base and more as a part of the business assets, since it is exactly with this API that we generate corresponding operational values.

If we integrate the business aspect, we should take a closer look at some terminology from this context in connection with APIs.

### Public APIs
As a first step we assume that we basically develop APIs as if they were publicly available, i.e. Public APIs. This assumption forces us to make sure right from the beginning of development that the API is easy to understand and use for every potential consumer through good design, implementation and documentation.

The role of the consumer in the API environment
We are dealing here with two types of consumers, the internal and the external. The external consumer is someone outside the actual business. It can be a specific user or a provider of another service. The internal consumer is part of the business. For both types of consumers, the internal consumer is usually a developer. From a business perspective, there is a corresponding value behind every transaction, whether internal or external. Thus, the API is to be seen as part of the value chain.

### Development
After dealing with the consumers, we should turn to the development of an API product. Development is basically a process that incurs costs and therefore represents an investment. This should be kept in mind when considering APIs in terms of a product. Before the concrete implementation is started, an MVP (Minimal Viable Product) is defined for the API product. This then includes a roadmap to guarantee that consumers get exactly what they really need. By this limitation within the development we prevent the implementation of features that are not needed, such as unused endpoints. Potential security gaps are thus reduced.

### Unchangeability
What you should never forget when developing an API is the immutability of the API. In the sense of the product idea this means that corresponding changes must be downward compatible, otherwise investments in the product are not reasonable.

### Measurability
Now that we have developed an API product and made it available to consumers, the question of the value of the product quickly arises. Here it is necessary now to measure or make measurable the use of the product accordingly. In this way, the business value of an API product can also be brought closer to a non-technical audience. For this audience, however, the number of APIs within the product is not decisive.

Here are some questions for the development of potential metrics:

- How long does it take to register to use the API?
- After how long does the user receive the first 200 response from the API?
- How often has the API been shared across social networks?
- Another important aspect of measurability is the continuous influence on the roadmap, as we now have a - direct feedback loop to the consumer.
- Availability and publicity
To make an API product available and known to consumers, a developer portal is often used. This portal enables consumers to learn about and use the offered API on their own.

### Security
Safety is also an important factor for API products. They should therefore be protected by OAuth, API Key Verification, XML/JSON Threat Protection and general security mechanisms.

### Conclusion
In order to establish an API as a product within the digital transformation of a business, we must keep the above-mentioned points in mind during implementation. After all, the product ensures that applications and systems can be connected to each other from anywhere and at any time.

API as a Product insights

<p>The last post in our series on Reedelk was about implementing an ETL process that can be triggered by a rest endpoint. Now this service should be made available to the “outside world” in a secured way. But how can services in modernization projects be secured in a simple way? In this case it makes sense to think about using an API Gateway. What an API Gateway is and how it works has already been discussed in several <a href="https://blog.codecentric.de/en/?s=kong&x=0&y=0" target="_blank">posts</a>  on our blog. With regard to the enterprise context in which the project is moving, the project coincides with the already known Kong Enterprise, which is currently available in version 2.1. If only the pure gateway would be discussed here, Kong could also be used in the Community Edition.</p><h2>The Encounter of Elk and Gruce</h2><p>The basis of all following considerations and corresponding implementations is again the “API first” approach. In the previous <a href="https://blog.codecentric.de/en/2020/09/creating-integration-flows-reedelk-data-integration-platform/" target="_blank">post</a> , the API specification was used to create the integration service in basis. Now the spec is intended to promote the service at the gateway and also to make it known to users, i.e. developers, via a so-called developer portal. First of all the Docker Compose file will be extended by Kong Enterprise and another PostgreSQL.</p>

```code-highlighted code-yaml
version: "3"
networks:
  int-net:
    driver: bridge
services:
  bookings:
    image: postgres:11.7-alpine
    networks:
      - int-net
    container_name: bookings
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
    ports:
      - 5433:5432
    volumes:
      - ./db/10_init.sql:/docker-entrypoint-initdb.d/10_init.sql
      - ./postgres-bookings:/var/lib/postgresql/data
    healthcheck:
      test: [ "CMD", "pg_isready", "-U", "postgres" ]
      interval: 90s
      timeout: 5s
      retries: 5
  booking-integration-service:
    build: .
    depends_on:
      - bookings
    ports:
      - 8484:8484
      - 9988:9988
    networks:
      - int-net
    container_name: booking-integration-service
  kong-db:
    image: postgres:9.6
    restart: always
    networks:
      - int-net
    container_name: kong-db
    environment:
      - POSTGRES_USER=kong
      - POSTGRES_PASSWORD=kong
      - POSTGRES_DB=kong
    volumes:
      - ./postgres-kong:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
  kong-migration:
    image: kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition:latest
    command: kong migrations bootstrap
    restart: on-failure
    networks:
      - int-net
    container_name: kong-migration
    environment:
      - KONG_PG_HOST=kong-db
      - KONG_PG_PASSWORD=kong
      - KONG_DATABASE=postgres
      - 'KONG_LICENSE_DATA=${KONG_LICENSE_DATA}'
      - KONG_PASSWORD=${KONG_PASSWORD}
    depends_on:
      - kong-db
  kong-enterprise:
    image: kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition:latest
    depends_on:
      - kong-migration
      - kong-db
    restart: always
    networks:
      - int-net
    container_name: kong-enterprise
    ports:
      - 8000:8000
      - 8001:8001
      - 8002:8002
      - 8003:8003
      - 8004:8004
      - 8005:8005
    environment:
      - KONG_ENFORCE_RBAC=on
      - KONG_ADMIN_GUI_AUTH=basic-auth
      - KONG_ADMIN_GUI_SESSION_CONF=${KONG_ADMIN_GUI_SESSION_CONF}
      - KONG_AUDIT_LOG=on
      - KONG_LOG_LEVEL=debug
      - KONG_PORTAL_GUI_HOST=localhost:8003
      - KONG_PORTAL_GUI_PROTOCOL=http
      - KONG_PORTAL=on
      - KONG_PORTAL_AUTH=basic-auth
      - KONG_PORTAL_SESSION_CONF=${KONG_PORTAL_SESSION_CONF}
      - KONG_ADMIN_GUI_URL=http://localhost:8002
      - KONG_DATABASE=postgres
      - KONG_PG_PASSWORD=kong
      - KONG_PG_HOST=kong-db
      - KONG_PG_DATABASE=kong
      - KONG_CASSANDRA_CONTACT_POINTS=cassandra
      - 'KONG_LICENSE_DATA=${KONG_LICENSE_DATA}'
      - KONG_VITALS=on
      - KONG_ANONYMOUS_REPORTS=off
      - KONG_PROXY_ACCESS_LOG=/dev/stdout
      - KONG_ADMIN_ACCESS_LOG=/dev/stdout
      - KONG_PROXY_ERROR_LOG=/dev/stderr
      - KONG_ADMIN_ERROR_LOG=/dev/stderr
      - KONG_PROXY_LISTEN=0.0.0.0:8000, 0.0.0.0:8443 ssl
      - KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl
      - KONG_ADMIN_GUI_LISTEN=0.0.0.0:8002, 0.0.0.0:8445 ssl
      - KONG_PORTAL_GUI_LISTEN=0.0.0.0:8003, 0.0.0.0:8446 ssl
      - KONG_PORTAL_API_LISTEN=0.0.0.0:8004, 0.0.0.0:8447 ssl
      - KONG_VITALS_STRATEGY=database
```

<p>Now the following architecture is available:</p><figure><a href="https://media.graphassets.com/U5hmaTE5Td6iCNx9dkPe"><img width="250" height="205" src="https://media.graphassets.com/U5hmaTE5Td6iCNx9dkPe" alt="Basic architecture" /></a> </figure><h2>From OpenAPI spec to configuration as code</h2><p>To promote the integration service at the gateway, the first step is to use <a href="https://blog.codecentric.de/en/2020/06/introduction-to-insomnia-designer/">Insomnia Designer</a> . Through the “Kong Bundle” plugin, Insomnia Designer is able to create a configuration for the Kong gateway based on an OpenAPI specification. By adding an OpenAPI extension (x-), configuration parameters for services can be included in the API specification. To keep the demo YAML file simple, the plugin configuration is located directly on the server level to provide a security configuration for the whole service.</p>

```code-highlighted code-yaml
openapi: 3.0.2
info:
  title: Bookings API
  description: API for Bookings
  version: 0.2.0
servers:
  - url: http://host.docker.internal:8484/
    x-kong-plugin-key-auth:
      name: key-auth
      enabled: true
      config:
        key_names: [api_key, apikey]
        key_in_body: false
        hide_credentials: true
paths:
  /bookings:
```

<p>Now in Insomnia Designer, the declarative configuration can be created with a single click and must then be manually copied to a corresponding file in the repository. Also a new workspace is created in Kong Enterprise.</p><figure><a href="https://media.graphassets.com/m7f9CtX9SOmaELdz8xKV"><img loading="lazy" width="250" height="115" src="https://media.graphassets.com/m7f9CtX9SOmaELdz8xKV" alt="Declarative Configuration" /></a> </figure>

```code-highlighted code-bash
http :8001/workspaces name=ccPlayground Kong-Admin-Token:<needstobesetinenvfile>
deck dump --workspace ccPlayground --skip-workspace-crud --headers kong-admin-token:<needstobesetinenvfile>
```

<p>By using <a href="https://blog.codecentric.de/en/2019/12/kong-api-gateway-declarative-configuration-using-deck-and-visualizations-with-konga/">DecK</a> , a configuration tool for the Kong Gateway, the configuration is synchronized and can be used directly.</p>

```code-highlighted code-bash
deck sync --workspace ccPlayground --skip-workspace-crud --headers kong-admin-token:<needstobesetinenvfile>
```

<p>The service created with Reedelk is registered at the gateway. Calling the service route <code>http :8001/services Kong-Admin-Token: <needstobesetinenvfile></code> returns</p>

```code-highlighted code-bash
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 392
Content-Type: application/json; charset=utf-8
Date: Tue, 15 Sep 2020 09:55:45 GMT
Server: kong/2.1.3.0-enterprise-edition
X-Kong-Admin-Latency: 48
X-Kong-Admin-Request-ID: uangDLXehlqnehUqqZBV1B95Jb6W8CCo
vary: Origin

{
    "data": [
        {
            "ca_certificates": null,
            "client_certificate": null,
            "connect_timeout": 60000,
            "created_at": 1600150691,
            "host": "localhost",
            "id": "bb9d1b9c-d1e4-4271-92cf-23e32544c72f",
            "name": "Bookings_API",
            "path": "/",
            "port": 8484,
            "protocol": "http",
            "read_timeout": 60000,
            "retries": 5,
            "tags": [
                "OAS3_import"
            ],
            "tls_verify": null,
            "tls_verify_depth": null,
            "updated_at": 1600150691,
            "write_timeout": 60000
        }
    ],
    "next": null
}
```

<p>The service with its end points is now behind the gateway. To use the KeyAuth plugin, a consumer must still be created. For this consumer a key will be created as well.</p>

```code-highlighted code-bash
http POST :8001/ccPlayground/consumers username=bookings Kong-Admin-Token:<needstobesetinenvfile>
http POST :8001/ccPlayground/consumers/bookings/key-auth Kong-Admin-Token:<needstobesetinenvfile>
```

<p>The key (visible in the lower code block) can now be used for the call via the gateway.</p>

```code-highlighted code-bash
HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 190
Content-Type: application/json; charset=utf-8
Date: Tue, 15 Sep 2020 14:03:16 GMT
Server: kong/2.1.3.0-enterprise-edition
X-Kong-Admin-Latency: 89
X-Kong-Admin-Request-ID: 0DaEWPpwa2IZ0xTH9X08BLjI3Cl20t2l
vary: Origin

{
    "consumer": {
        "id": "c06250bf-a018-478a-a60b-bd739b1af820"
    },
    "created_at": 1600178596,
    "id": "0b4ea73e-dde8-4c2f-8b6c-0ecd0c227da1",
    "key": "S0llbYJjebrNoCG4PURHyjNPUK2Yv9Ds",
    "tags": null,
    "ttl": null
}
```

<p>Calling the route <code>http :8000/bookings/00002D apikey:S0llbYJjebrNoCG4PURHyjNPUK2Yv9Ds</code> on the gateway now returns the following response.</p>

```code-highlighted code-bash
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 81
Content-Type: application/json
Via: kong/2.1.3.0-enterprise-edition
X-Kong-Proxy-Latency: 1
X-Kong-Upstream-Latency: 254

[
    {
        "book_date": "2017-05-20 15:45:00.0",
        "book_ref": "00002D",
        "total_amount": 114700
    }
]
```

<h2>Adding some developer experience</h2><p>After the Booking Integration Service has been granted an authorization, the main focus will be on the developer portal. For this purpose it will be activated via the Admin Rest API of Kong Enterprise.</p>

```code-highlighted code-bash
http PATCH :8001/workspaces/ccPlayground Kong-Admin-Token:<needstobesetinenvfile> config.portal=true -f
```

<p>Subsequently, Insomnia Designer is used to deploy the API spec to the existing portal.</p><figure><a href="https://media.graphassets.com/H5xLoVQ4Sy6TzOaXLN4R"><img loading="lazy" width="250" height="115" src="https://media.graphassets.com/H5xLoVQ4Sy6TzOaXLN4R" alt="Deploy Spec to Portal" /></a> </figure><p>With the portal one wants to deliver an improved user experience (UX), in particular a developer experience (DX) for APIs. The simplest form, more precisely the entry page of such a portal is the catalog of all available APIs, as shown in the picture.</p><figure><a href="https://media.graphassets.com/RqPszAoFREmcKb6ZGBfS"><img loading="lazy" width="250" height="137" src="https://media.graphassets.com/RqPszAoFREmcKb6ZGBfS" alt="API Catalogue" /></a> </figure><p>Kong Enterprise is able to create a developer portal for each workspace, either via the Admin Rest API or the Kong Manager. Through workspaces, current APIs can be grouped according to individual categorization. This can also be a first step towards <a href="https://blog.codecentric.de/en/2020/09/api-as-a-product-insights/" target="_blank">API as a Product</a> . Each portal can be completely customized to individual needs. For the developer of a possible client, supported by the plugin “Application Registration”, the DX can be improved even further.</p>

```code-highlighted code-bash
http POST :8001/ccPlayground/services/Bookings_API/plugins name=application-registration Kong-Admin-Token:<needstobesetinenvfile> config.auto_approve=false config.description="All about bookings" config.display_name=Bookings config.show_issuer=false -f
```

<p>With the help of the plugin, client applications can now be registered directly via the portal and coupled with the corresponding services.</p><figure><a href="https://media.graphassets.com/GiDRcZxeSEunE19GIUDp"><img loading="lazy" width="250" height="141" src="https://media.graphassets.com/GiDRcZxeSEunE19GIUDp" alt="Application Registration" /></a> <br /> <a href="https://media.graphassets.com/3XCVvSgBTcGizEyXS5Ai"><img loading="lazy" width="250" height="141" src="https://media.graphassets.com/3XCVvSgBTcGizEyXS5Ai" alt="Application Registration Details" /></a> </figure><p>This form of self-service helps enormously to further promote the distribution and use of the APIs created.</p><p>With these few steps, the integration service has now been secured by a gateway, in particular Kong Enterprise, and at the same time access for APIs has been improved through a developer portal. The use of API first, Kong’s Admin Rest API and Configuration as Code also shows which steps can be automated in terms of a CI/CD pipeline.<br /> This is now a way to integrate Reedelk with Kong. In a following blogpost I would like to introduce the Kong Reedelk Transformer plugin, which is another approach to integrate the two components. The sources for the demo project are available at <a href="https://github.com/codecentric/reedelk-bookingintegrationservice" target="_blank">GitHub</a> .</p>

Offloading and more from Reedelk Data Integration Services through Kong Enterprise

When thinking about the development of microservices and their connectivity, one inevitably stumbles across the terms / patterns of API gateway and service mesh. But why do these patterns or technologies exist at all? Sometimes it also happens that the patterns are mixed up with each other in terms of content, because a deeper understanding of the application of the patterns is missing and a tutorial is not necessarily the best basis. To begin with, it is important to take a look at the OSI network layer model. This model is the basis for all subsequent considerations.

### OSI network layer model
![osi_model_banner.png](https://media.graphassets.com/HfJ2IerRQlKoXiIjmm0E)

The model describes the relevant network protocols in the form of layers as a reference. Throughout this blog post, we will return to this model again and again.
The API gateway has yet been described in detail in various blogposts, but here we will summarise the most important points for a possible comparison with a service mesh.

API Gateway and Service Mesh in the context of service connectivity

<p>In my <a href="https://blog.codecentric.de/en/2021/01/apiops-automated-processes-for-even-better-apis/">last post on APIOps</a> , I looked at API first as a strategy for designing APIs. But how can APIs created in this way be found and standardized? And how can they be made usable and secure? In this article, I would like to take a deeper look at the increasingly common term API governance and show how this concept can help speed up the design process.</p><h2>What is API governance?</h2><p>API governance is a method of applying common rules related to standards of APIs. It also often includes the development of APIs based on a common data model with reusable resources or model objects. Finally, governance can be used to ensure that APIs are sufficiently enriched with metadata so that they can be easily used by a broader audience, both within an organization and externally.</p><h2>Who needs it?</h2><p>In simple terms, API governance is important for any organization implementing an API-first strategy, where APIs are at the core of their transformation to a digital enterprise. It is also important for anyone planning or already implementing a distributed microservices environment. There is one specific use case where API governance is absolutely business-critical: large enterprises. That’s because they need thousands of consistent, secure and reusable APIs – representing both business and IT functions – rather than a handful of well-documented public APIs in an API portal.</p><h2>How does governance help establish speed in API design?</h2><p>To build speed, a wide variety of issues need to be reconciled. The first one is to give a central core to the issues around APIs. In the literature, you will often find the term “Center for Enablement” (C4E in short). This is crucial for the introduction of governance, as it provides the appropriate framework for all further action. This also includes introducing API first in a purposeful and continuous manner, which must be supported by centrally controlled API governance. Only this ensures consistent and reusable APIs, which in turn also lead to organization-wide standardization. This requires creating and enforcing design guidelines for all APIs, regardless of the underlying architectural style (SOAP, REST, event-based). However, the design guidelines also simplify the already mentioned reusability. This is done on the basis of so-called Information Models (also known as Canonical Models in the age of SOA), i.e. proven model objects and resources that standardize organization-wide information in predefined structures.<br /> The process, the API lifecycle, in which APIs are found, basically consists of several phases. With the introduction of API governance, it is important to be able to apply it in all phases of the lifecycle. The easiest way to do this is through automation. I described one possible way of automation, APIOps, in detail in the blog article mentioned at the beginning. In the context of this post, I would like to briefly summarize the most important points.</p><p>APIOps can be integrated into already existing CI-/CD-processes by simple means, as these processes have to be extended or adapted. The specification of an API becomes Configuration as Code within the deployment to be available via a gateway accordingly. <a href="https://media.graphassets.com/WIIsEY5MSYmTeCH844iX"><img width="1024" height="576" src="https://media.graphassets.com/WIIsEY5MSYmTeCH844iX" alt="APIOps in Action" /></a> The image shows an example of this with the Kong Enterprise Gateway with additional portal using Insomnia and Inso CLI.</p><p>A version control system is always used for automation. Therefore, the desire to version an API arises over and over. However, as I noted in the <a href="https://blog.codecentric.de/en/2020/09/api-as-a-product-insights/">codecentric blog post</a>  on “API as a Product” in 2018, an API stands for immutability. This means that changes must always be backward-compatible. To ensure this, it’s worth keeping three short rules in mind:</p><p>1st rule: Don’t leave anything out!<br /> 2nd rule: Do not change the meaning of anything!<br /> 3rd rule: Everything added is optional.</p><p>When APIs are available for a long period of time, they may become obsolete. Again, define a policy within API governance that supports this process. This allows consumers to know when they should expect an API to become unavailable. Last but not least, the visibility of available APIs must be considered. The key here is to find a means to make APIs easily searchable and discoverable. Thus, it becomes clear that an API portal becomes a part of governance.</p><h2>Conclusion</h2><p>API governance helps save time and money by enabling consistency across APIs, allowing reuse of components, and ensuring that APIs are created proactively to achieve specific goals and add value to the organization. API governance also helps organizations make smart decisions about API programs and establish best practices for creating, deploying and using APIs.</p>

API first – now even faster!

<p>In my German <a href="https://info.codecentric.de/softwerker-vol-14" target="_blank">Softwerker article (Vol. 14, p. 90)</a> , I already dealt with the continuous design and development cycle of APIs. This was mainly about basic assumptions and tooling, including the introduction of API gateways or platforms into existing development cycles. In this post, I would now like to introduce automated processes for the design and development of APIs and services under the context of APIOps. When talking or writing about development processes, the term DevOps is usually always mentioned. Unfortunately, this is also always used in a very inflationary manner.</p><h2>So what is DevOps again?</h2><p>DevOps is a broad concept that encompasses several aspects of collaboration and communication between software developers and other IT professionals. The easiest way to define DevOps is to talk about its goals. DevOps aims to improve collaboration between development and operations teams throughout the software development process, from planning to delivery, to increase deployment frequency, achieve faster time to market, reduce the failure rate of new releases, shorten the lead time between fixes, and improve mean time to recovery.</p><p>One of the models that can be used when talking about DevOps is called CALMS, which stands for Collaboration, Automation, Lean, Measurement and Sharing. The CALMS model is a way to assess, analyze and compare the maturity of the DevOps team.</p><table><thead><tr><th><h3>CALMS model</h3></th></tr></thead><tbody><tr><td><h3>Collaboration</h3><p>Collaboration in the CALMS model means that people are above processes. An organization should value healthy people rather than processes, which can cause people to burn out and eventually quit their jobs. As part of the culture, it also embraces failure – giving people the freedom to fail and, more importantly, to learn from it. In this culture, ideas are valued by all; people do not favor the ideas of only certain people. Hierarchy and titles do not matter, and everyone participates in shaping the system.</p></td></tr><tr><td><h3>Automation</h3><p>Automation of the software lifecycle is critical to achieving greater speed and consistency of deployments. To be able to move from an implemented feature or code change to a deployed feature in production in a matter of minutes requires reliable automation. Key elements that need to be automated are infrastructure (IaC), continuous integration (CI) process, post-code testing, continuous deployment (CD), and testing along deployment paths. Ideally, and if possible, automation is already built into the platform and tools you use.</p></td></tr><tr><td><h3>Lean principles and processes.</h3><p>The focus of Lean principles and processes comes from manufacturing (specifically Toyota Production Systems). The core of Lean is to remove any waste from your processes. An example of how this can be achieved is to first draw and document the current state of your processes.</p><ul><li>What happens when you check in code, or what happens when you set up servers or environments?</li><li>How do you go from nothing in production to a production environment running applications?</li></ul><p>After all of this is recorded, you can estimate how long each part takes and easily identify bottlenecks, unnecessary processes, or manual processes. Once these are identified, they can either be eliminated or automated to speed up the process. After repeating this a few times, the desired lean state of the processes can be determined.</p></td></tr><tr><td><h3>Measurement</h3><p>To determine whether deployments and releases are successful, specific metrics are needed. The purpose of measurements is to quickly discover potential problems with the code or process so that, if needed, they can be gone back and fixed. So far, only system and application measurements have been mentioned, but people and cultural metrics should not be forgotten.</p><p>Measurements inform whether people are healthy or the impact of investments in the organization, in addition to how they affect how much money is made or how to innovate faster.</p></td></tr><tr><td><h3>Sharing</h3><p>Sharing insights and best practices is also important, both within the organization and between organizations within a company, as well as between potential competitors and the rest of the industry, with the goal of improving the industry for everyone.</p></td></tr></tbody></table><p>When you consider all the CALMS principles, they have one thing in common: people. You can’t be successful with DevOps if you don’t focus on people and make sure they work well together. Now the picture of DevOps should be a little clearer. At the same time, we have learned about CALMS as a way to measure progress in terms of using DevOps. However, this is still not enough to get to the APIOps announced in the title. For this, let’s look at another paradigm, GitOps.</p><h2>GitOps</h2><p>Through GitOps, versioning, or more precisely Git, is used for the entire management process of an application.This should also enable developers to perform tasks from the area of IT operations. GitOps can also be used to increase the maturity of process automation. A large part of API design and development takes place in operations through the use of API gateways. This leads to another level of APIOps.</p><h2>A continuous process</h2><p>The continuous development process continues to determine everything we do – and thus represents the starting point for all further considerations.</p><div><a href="https://media.graphassets.com/3UxNAqB3RN6Xc34q8Nbz"><img src="https://media.graphassets.com/3UxNAqB3RN6Xc34q8Nbz" alt="Continuous Lifecycle" width="1024" height="852" /></a> <p>Continuous Lifecycle</p></div><p>As already discussed in the previous article, there are two separate processes for the design and development of APIs, one for the producer side and one for the consumer side of an API. The focus will now be on the producer process.</p><div><a href="https://media.graphassets.com/nOg8lWooQ2SBgrvM5M9B"><img loading="lazy" src="https://media.graphassets.com/nOg8lWooQ2SBgrvM5M9B" alt="API Producer / Provider Continuous Lifecycle" width="916" height="485" /></a> <p>API Producer / Provider Continuous Lifecycle</p></div><h2>OpenAPI Spec</h2><p>When we look at the design of APIs, it also makes sense to follow the approaches of “API first” or “Spec first”. But what does this mean in concrete terms for automating an API development process? The design of an API basically starts with the creation of a specification based on the OpenAPI standard. I already described this procedure in my last article in Softwerker Vol. 14. But how do you write an OpenAPI spec and how does the topic of automation fit with it? Since most projects that require an API generate it based on the sources, the question of a general workflow did not really arise. If you start with “API first”, the first step is version control, or more precisely Git, since a central repository for the API specifications is needed.</p><h3>But do you really want to write APIs in JSON or YAML notation?</h3><p>With <a href="https://stoplight.io/studio/" target="_blank">Stoplight Studio</a> , such an editor is now available as a desktop application. In addition to the actual specification, JSON schemas and project documentation can also be captured on the basis of Markdown. The integration of <a href="https://stoplight.io/open-source/spectral" target="_blank">Spectral</a>  and <a href="https://stoplight.io/open-source/prism/" target="_blank">Prism</a>  provides support for linting and mocking. In combination with Git, all artifacts can be placed under version control.</p><div><a href="https://media.graphassets.com/OZh5ojtwQN6rd94DObRS"><img loading="lazy" src="https://media.graphassets.com/OZh5ojtwQN6rd94DObRS" alt="Stoplight Studio Visual Editor" width="1024" height="527" /></a> <p>Stoplight Studio Visual Editor</p></div><p>In addition to Stoplight Studio, <a href="https://www.postman.com/downloads/" target="_blank">Postman</a>  is more a Suite than an editor even when the desktop version is used. We will have a look at the additional API lifecycle possibilities of Postman in a future blog post. Strictly speaking, when an API is published, a configuration for the API platform or gateway is also required. This can be done through the OpenAPI Extensions. Extensions (also called Specification Extensions or Vendor Extensions) are user-defined properties that start with x-, such as x-codecentric. They can be used to describe additional functionality that is not covered by the standard OpenAPI specification. Many API-related products that support OpenAPI use extensions to document their own attributes. Currently, Stoplight Studio does not allow this with the visual editor, but it is on the roadmap for upcoming releases. However, the extensions can be viewed and edited via the code view.</p><div><a href="https://media.graphassets.com/xdhEKUPSbuTIPwE7nsQ7"><img loading="lazy" src="https://media.graphassets.com/xdhEKUPSbuTIPwE7nsQ7" alt="Stoplight Studio Code Editor" width="1024" height="527" /></a> <p>Stoplight Studio Code Editor</p></div><h2>Everything as/with code</h2><p>For the configuration of an API gateway or platform, information in the form of JSON or YAML files is mandatory. The OpenAPI specs created can support configuration through centrally set key/values. But to apply this directly to the API gateway, we need a transformation of the spec to Configuration as Code. Here we now need to check what possibilities the API Gateway offers for integration based on a CI/CD pipeline. Detailed insights into the possibilities of automation based on Everything as Code can be found in an <a href="https://blog.codecentric.de/en/2020/11/spring-boot-kong/">article by Jonas Hecht</a>  on the codecentric blog.</p><h2>Policy as Code</h2><p>Now that the infrastructure and the configuration of the API delivery pipeline based on “as code” are in place, the question arises of how the sometimes complex access structures to an API via an API gateway or general compliance policies according to standards such as PCIDSS, SOC or DSGVO can also be mapped in an automation. Hashicorp has coined the term “policy as code” for this. However, this article would like to take a look at <a href="https://www.openpolicyagent.org" target="_blank">Open Policy Agent</a>  (OPA) in this context. OPA decouples the setting of policies from the enforcement of them. Now, when a component like an API gateway needs to make decisions according to a policy, it queries this to the agent and provides JSON data as input for this. The agent now generates its decision based on the input and the policy and additional data.<br /> Thus, policies can also become part of an existing automated process. This should also suffice for now as an introduction to the topic “Policy as Code”.</p><h2>Conclusion</h2><p>The created term APIOps is made up of many topics and sub-aspects that have been known for a long time, such as</p><ul><li>DevOps (in particular CI/CD)</li><li>GitOps</li><li>Everything as Code</li></ul><p><a href="https://media.graphassets.com/BLr0LkidTAe4MRsUtjd4"><img loading="lazy" width="1024" height="576" src="https://media.graphassets.com/BLr0LkidTAe4MRsUtjd4" alt="APIOps in Action" /></a> <br /> All of the elements shown can support and further automate existing processes, with the “API first” approach being the foundation of everything.</p>

APIOps – Automated processes for even better APIs

<p>The integration of data from systems of record or legacy systems is one of the elements of a software development project that does not start on a greenfield. In other words, it can help modernize software. Usually the question arises how to transfer the addressed data into the “new” world without much effort.</p><h2>ESB, ETL and ELT are not dead</h2><p>If you look at the use case schematically, it is basically about ETL (Extract-Transform-Load) or ELT (Extract-Load-Transform) processes. Nowadays, Kafka is very quickly taken as a super weapon or panacea, and this blog post will show that this is not always the best solution. The Enterprise Service Bus has a long tradition in software development.</p><p>And it is exactly this functionality that the Reedelk Data Integration Platform wants to map in a simple way. The product is relatively new on the market, more precisely as a community edition since the end of June 2020.</p><p>IntelliJ as a development environment provides the foundation and is extended with a plugin, the Reedelk Flow Designer (https://www.reedelk.com/documentation/intellijplugin). A similar model is offered by MuleSoft and RedHat, where both rely on Eclipse and also deliver a complete development environment. However, the Flow Designer is currently closed source for the platform (community edition), but it is available free of charge. The created runtimes can be deployed in the cloud in various ways. Detailed information can be found in the documentation (https://www.reedelk.com/documentation/runtime). The option to create a Docker container is delivered directly with each runtime project created and thus the different deployment types can be created via build pipeline mechanisms. Since version 1.0.1 OpenAPI Import Tool has also been integrated, thus the platform now supports the API-first approach.</p><h2>An integration project</h2><p>Now we want to take a look at the platform with the help of a demo project. The idea here is the concrete implementation of the use case mentioned at the beginning. Our fictitious customer has an old legacy application whose data should now be made available to newer applications with the help of APIs. The data model looks like this:</p><figure><a href="https://media.graphassets.com/QTSp6OCERcmQrBITDLRx"><img width="250" height="145" src="https://media.graphassets.com/QTSp6OCERcmQrBITDLRx" alt="Database schema" /></a> </figure><h3>The setting</h3><p>The demo is based on the PostgreSQL example DB “Airlines”. The legacy system is an old booking system. The main entity is a booking (<code>bookings</code>). A booking can include several passengers, where a separate ticket (<code>tickets</code>) is issued for each passenger. A ticket has a unique number and contains information about the passenger. As such, the passenger is not a separate entity. Both the name of the passenger and the number of his or her ID card may change over time, making it impossible to uniquely identify all tickets for a particular person; for the sake of simplicity, we can assume that all passengers are unique. The ticket includes one or more flight segments (<code>ticket_flights</code>). Several flight segments may be included in a single ticket if there are no non-stop flights between the point of departure and destination (connecting flights) or if it is a round-trip ticket. Although there is no restriction in the scheme, it is assumed that all tickets in the booking have the same flight segments. Each flight (<code>flights</code>) goes from one airport (<code>airports</code>) to another. Flights with the same flight number have the same origin and destination, but differ in the departure date. At flight check-in, the passenger is issued a boarding pass on which the seat number is indicated. The passenger can only check in for the flight if this flight is included in the ticket. The combination of passenger and seat must be unique to avoid issuing two boarding passes for the same seat. The number of seats (<code>seats</code>) in the aircraft and their distribution among different classes depends on the model of the aircraft (<code>aircrafts</code>) making the flight. It is assumed that each aircraft model has only one cabin configuration.</p><p>Thus, the initial situation would be clear. The task now is to make the booking system easier to integrate with the help of Reedelk. In addition to the aforementioned integration platform, IntelliJ, OpenAPI and Docker are also used. In order to start, a Reedelk project is created in IntelliJ.</p><figure><a href="https://media.graphassets.com/xHDtWSp5StC1ECMhg4Gl"><img loading="lazy" width="250" height="144" src="https://media.graphassets.com/xHDtWSp5StC1ECMhg4Gl" alt="Create a Reedelk project" /></a> </figure><p>Within the project, an appropriate PostgreSQL database, which represents the legacy system, is made available via Docker and a Docker Compose file.</p>

```code-highlighted code-yaml
version: "3"
services:
  bookings:
    image: postgres:11.7-alpine
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
    ports:
      - 5432:5432
    volumes:
      - ./db/10_init.sql:/docker-entrypoint-initdb.d/10_init.sql 
```

<h3>API first</h3><p>Next, the OpenAPI specification for the bookings entity is created. The result is shown in the following codeblock.</p>

```code-highlighted code-yaml
openapi: 3.0.3
info:
  title: Bookings API
  description: API for Bookings
  version: 0.1.0
servers:
  - url: http://localhost
paths:
  /bookings:
    get:
      summary: Returns a list of bookings.
      description: A list of bookings.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Booking'
              example:
                - book_ref: 00004A
                  book_date: 2016-10-13 18:57:00.000000
                  total_amount: 29000.00
                - book_ref: 00006A
                  book_date: 2016-11-05 02:02:00.000000
                  total_amount: 106100.00
        '404':
          description: Error
    post:
      summary: Creates new booking.
      description: A new booking is created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
            example:
              book_ref: 12345A
              book_date: 2020-08-26 07:51:00.000000
              total_amount: 10000.00
      responses:
        '201':
          description: Booking created
        '404':
          description: Error
  /bookings/{booking_ref}:
    get:
      summary: Returns a booking by booking_ref.
      description: An unique booking by booking_ref.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Booking'
              examples:
                bookingGETExample:
                  $ref: '#/components/examples/bookingGetExample'
        '404':
          description: Error
    put:
      summary: Updates an existing booking.
      description: An existing booking will be updated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
            examples:
              bookingPUTExample:
                $ref: '#/components/examples/bookingPutExample'
      responses:
        '200':
          description: OK
        '404':
          description: Error
components:
  schemas:
    Booking:
      properties:
        book_ref:
          type: string
        book_date:
          type: string
          format: 'date-time'
        total_amount:
          type: number
          format: double
  examples:
    bookingGetExample:
      value:
        book_ref: 00006A
        book_date: 2016-11-05 02:02:00.000000
        total_amount: 106100.00
    bookingPutExample:
      value:
        book_ref: 00006A
        book_date: 2016-11-05 02:02:00.000000
        total_amount: 10600.00
```

<p>The API import tool integrated in the Flow Designer is currently only able to process the sample data as inline samples.</p><p>Via <code>Tools\Import Open API</code> the following four flows can now be generated from the spec.</p><ul><li><code>GETBookings</code></li><li><code>GETBookingsBooking_ref</code></li><li><code>POSTBookings</code></li><li><code>PUTBookingsBooking_ref</code></li></ul><figure><a href="https://media.graphassets.com/QujwCx6vSgOXlv3gjtQ6"><img loading="lazy" width="250" height="175" src="https://media.graphassets.com/QujwCx6vSgOXlv3gjtQ6" alt="Import Open API Spec" /></a> </figure><p>By using the API-first approach, the corresponding examples from the specification were stored within the flow in addition to the flows, so that the integration service created can be made available directly to consumers of the service in the stage for development and testing, as a container using Docker, for example. This now also enables asynchronous and parallel development of clients and service.</p><h3>Let the integration flow</h3><p>At this point, the task is to create the connection to the database for <code>GETBookings</code> flow. This can be done by the Flow Designer or in a textual way. A flow is always based on an ‘event’. This can be a consumer, listener or scheduler. This ‘event’ then triggers a chain of further actions.</p><figure><a href="https://media.graphassets.com/yLHFKkjCQJSwJD8A2ibI"><img loading="lazy" width="250" height="213" src="https://media.graphassets.com/yLHFKkjCQJSwJD8A2ibI" alt="Generated flow - Designer view" /></a> </figure><figure><a href="https://media.graphassets.com/YkEyHMurTtCm4JhQbvXS"><img loading="lazy" width="250" height="213" src="https://media.graphassets.com/YkEyHMurTtCm4JhQbvXS" alt="Get all Bookings - SQL View Properties" /></a> </figure><p>First of all, access to the database is now required. For this purpose the SQL select component is dragged into the flow. In the next step the added component has to be configured. To do so, a global configuration file for the connection to the database is created in the Flow Designer interface. Afterwards only the appropriate SQL statement must be entered.</p><figure><a href="https://media.graphassets.com/cYHhfKj1TUiEDNPSlhjg"><img loading="lazy" width="250" height="44" src="https://media.graphassets.com/cYHhfKj1TUiEDNPSlhjg" alt="Get all Bookings - SQL Properties" /></a> </figure><p>As the data should be transferred to the client in JSON format, the Object-to-JSON component is required and must be placed behind the SQL component in the flow by means of drag-and-drop.</p><figure><a href="https://media.graphassets.com/L9E2Xz0jRGCuwMmQIuSy"><img loading="lazy" width="250" height="220" src="https://media.graphassets.com/L9E2Xz0jRGCuwMmQIuSy" alt="<img title=&quot;finalized Get all bookings flow&quot; src=&quot;flow_get_bookings.png&quot; />" /></a> </figure><p>The first flow for querying all bookings through an API is now complete. This is a simple flow that does not contain any business logic. It transforms the data into the JSON format.</p><p>By starting the Reedelk Runtime, the created flow can be tested locally. To test the API endpoint, Insomnia Designer will be used, as it allows importing the specification via a URL. The Reedelk Runtime provides such an endpoint for the created service under the URL <code>http:/localhost:8484/v1/openapi.yaml</code>.</p><figure><a href="https://media.graphassets.com/Lu87K5RiR0if7AMvrBSB"><img loading="lazy" width="250" height="137" src="https://media.graphassets.com/Lu87K5RiR0if7AMvrBSB" alt="Insomnia Designer - Documents view" /></a> </figure><p>When the GET endpoint is queried, the database is relatively big. The table <code>bookings</code> contains over 2 million entries. The specification already contains the endpoint <code>bookings/{booking_ref}</code>, which can be used to query the booking for a specific booking reference. We can replace the existing mock with two components (SQL Select and Object-to-JSON), so this flow also returns a desired JSON as response. The select statement in the SQL Select component has to be configured according to the screenshot.</p><figure><a href="https://media.graphassets.com/CKX70hqRnCpnBqSrlgy2"><img loading="lazy" width="250" height="45" src="https://media.graphassets.com/CKX70hqRnCpnBqSrlgy2" alt="Get Booking by booking_ref - SQL Properties" /></a> </figure><p>Two integration flows have already been created with the Reedelk Runtime and Platform, repsectively, based on an OpenAPI specification. The challenge of the large amount of data for the endpoint <code>/bookings</code> will be considered separately in an upcoming blog post.</p><h3>Creating a service for the cloud</h3><p>Finally the created integration service should be provided as a container. Based on Maven, this is not too much effort. With <code>mvn clean package</code>, a package is created. A Docker file is already created when the project is started.</p>

```code-highlighted code-yaml
FROM reedelk/reedelk-runtime-ce:1.0.5
COPY target/*.jar /opt/reedelk-runtime/modules
COPY reedelk-runtime/lib/*.jar /opt/reedelk-runtime/lib
CMD runtime-start
```

<p>In the next step the image can be built and then started.</p>

```code-highlighted code-bash
$ docker build -t booking-integration-service:0.1.0
$ docker run -p 9988:9988 -p 8484:8484 booking-integration-service:0.1.0
```

<p>Thus, the use case is solved for two API endpoints. The integration service is available, but access is currently completely uncontrolled. A proper control can be achieved by using an API gateway. An upcoming blog post will show what this could look like for the described use case. The sources for demo project are available at <a href="https://github.com/codecentric/reedelk-bookingintegrationservice" target="_blank">GitHub</a> .</p>

Creating integration flows with the Reedelk Data Integration Platform

<p>Most applications today are distributed and loosely coupled – which in turn means that the architecture consists of many self-contained components that may be maintained by different teams. The information that is exchanged between components should be visibly documented and maintained. In the realm of REST APIs, there is already an existing standard: <a href="/wissens-hub/blog/api-first-services-spring-boot/">OpenAPI</a>  (see <a href="https://www.openapis.org" target="_blank">web page</a> ). AsyncAPI (see <a href="https://www.asyncapi.com" target="_blank">web page</a> ) is a new counterpart for event- and message-driven architectures which was developed on the basis of OpenAPI. From an OpenAPI perspective, this makes it easier to start using.<br /> Compared to OpenAPI, AsyncAPI is more agnostic in its approach with regard to possible protocols. Currently, the following protocols are supported: AMPQ(S), HTTP(S), IBM MQ, JMS, (Secure) Kafka, (Secure) MQTT, STOMP(S), (Secure) WebSocket and Mercure. In order to make this article more than just an introduction, I would like to demonstrate the use of AsyncAPI in practice with a simple use case.</p><h2>OpenAPI vs. AsyncAPI</h2><p>Before we get into the use case in detail, I would like to take a closer look at two points: Firstly, I would like to draw a comparison between OpenAPI and AsyncAPI and secondly, I would like to shed light on the difference between events and messages. As already described in the introduction, AsyncAPI emerged from OpenAPI. One aim is to create as much compatibility as possible between the two specifications so that it is possible to reuse parts. Reusability makes a lot of sense, especially with regard to the data models within <code>Components</code>.</p><p><img src="https://media.graphassets.com/Ub4K7UptS46Gk8UqW00y" alt="Comparison of OpenAPI and AsyncAPI — (c) https://www.asyncapi.com/docs/getting-started/coming-from-openapi" /></p><div>Figure 1. Comparison of OpenAPI and AsyncAPI —- © <a href="https://www.asyncapi.com/docs/getting-started/coming-from-openapi">https://www.asyncapi.com/docs/getting-started/coming-from-openapi</a> </div><p>Figure 1 shows that the two specifications are really very similar in structure. In comparison to OpenAPI, <code>channels</code> are listed in the AsyncAPI. The <code>channels</code> are then also described protocol-agnostically in contrast to the <code>paths</code>. A complete description of the specification can be found at <a href="https://www.asyncapi.com/docs/specifications/v2.1.0" target="_blank">https://www.asyncapi.com/docs/specifications/v2.1.0</a> . After looking at the comparison between the two specifications, messages and events still need to be considered. The <a href="https://www.reactivemanifesto.org/glossary#Message-Driven" target="_blank">Reactive Manifesto</a>  contains a description of the difference, which I would like to briefly reproduce here. In a message-driven architecture, the producer knows the consumer. In event-driven architectures, on the other hand, the consumer decides which sources they want to subscribe to.</p><h2>The use case</h2><p>For the use case, a message regarding an order is to be transmitted from a producer via a queue to a consumer. In this case, RabbitMQ takes over the part of the message broker. The exact specification is now created via AsyncAPI. Any editor is sufficient to create the document. When using <a href="https://github.com/stoplightio/spectral" target="_blank">Spectral</a>  as a linter, it should be noted that it does not currently support the latest specification 2.1.0.</p><h3>The specification</h3><p>Every AsyncAPI-Spec starts with<br /> <code>asyncapi: '2.1.0'.</code></p><p>This is followed by the description of the <em>info</em> object.</p>

```highlight
info:
  title: Order Service
  version: 1.0.0
  description: The service is in charge of processing orders
  contact:
    name: Daniel Kocot
    email: daniel.kocot@codecentric.de
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  rabbitmq:
    url: localhost:5672
    description: RabbitMQ
    protocol: amqp
    protocolVersion: '0.9.1'
```

<p>As with OpenAPI, all information about the service is specified under <em>info</em> and <em>servers</em>. A key difference is the explicit specification of the protocol and its version in relation to the message broker under <em>servers</em>. The description of the service and the general setup is followed by the channel and the description of the respective operations. The specification contains a <em>channel item</em> object which refers to topics, routing keys, event types and paths.</p>

```highlight
channels:
  order-received:
    publish:
      operationId: orderReceivedPub
      description: Payload of received order
      message:
        $ref: '#/components/messages/order'
      bindings:
        amqp:
          timestamp: true
          ack: false
          bindingVersion: 0.2.0
    subscribe:
      operationId: orderReceivedSub
      description: Payload of received order
      message:
        $ref: '#/components/messages/order'
    bindings:
      amqp:
        is: routingKey
        exchange:
          name: orderExchange
          type: direct
          durable: true
          vhost: /
        bindingVersion: 0.2.0
```

<p>The <code>channel</code>-item object just mentioned now describes all operations of the respective channel in detail. However, there are only two <code>operation</code> objects, <code>publish</code> and <code>subscribe</code>.</p><table><tbody><tr><td><code>publish</code></td><td>Messages that are consumed by the application via the channel.</td></tr><tr><td><code>subscribe</code></td><td>Messages that are created by the application and sent to the channel.</td></tr></tbody></table><p>Via <code>bindings</code>, protocol-specific configurations can be carried out on the server, channel, operation and message levels. The bindings each have their own versioning. This must also be explicitly specified. Now let’s take a concrete look at the configuration on the channel level. The <em>is</em> property defines the type of channel. This can be either <code>queue</code> or <code>routingKey</code>, which is also the default value. Depending on the value, either a queue or an exchange must be described. In our case, it means that the message is not forwarded directly to the consumer, but is first passed to the exchange, which directs the message to a specific queue. The binding briefly describes how the channel functions within the messaging component. Within the description of the channel we also find the payload. This references a <code>Message</code> object, which is also the last element of the specification.</p>

```highlight
components:
  messages:
    order:
      payload:
        type: object
        properties:
          id:
            type: integer
            format: int64
            description: ID of received order
          customerReference:
            type: string
            description: Reference for the customer according the order
```

<p>Like the <code>Schema</code> object of the OpenAPI specification, the <code>Message</code> object is located below the <code>Components</code> object, but does not replace it in any way. Within the <code>Components</code> object, all reusable objects of a specification are grouped together and can be integrated via references. The AsyncAPI specification can also contain extensions, the <em>Extensions</em>. However, these are not used in the example.</p><h3>Creating documentation</h3><p>Now that we have worked our way through the specification for our use case, the question is how to turn this textual file into readable documentation for further use. Similar to OpenAPI, additional tooling is needed here. First, I would like to introduce the <a href="https://github.com/asyncapi/generator" target="_blank">generator</a> . In contrast to OpenAPI, the generator is written in JavaScript and is made available via npm or Docker. It can be used to create documentation in HTML or Markdown. It is also possible to generate initial snippets for certain programming languages and frameworks. We will disregard this option for the time being in this article. After the installation with <code>npm npm install -g @asyncapi/generator</code> we create a documentation artefact with the command <code>ag</code>.</p>

```highlight
api-showcases/async on  main [?] on ☁️
➜ ag order-service.yaml @asyncapi/html-template


Done! ✨
Check out your shiny new generated files at /Users/danielkocot/api-showcases/async.
```

<p>If we now open the corresponding index.html, the documentation looks like in the screenshot below.</p><p><img src="https://media.graphassets.com/OKijZNbdREaYQ2rl8dr5" alt="Generated AsyncAPI HTML Documentation" /></p><p>Besides using the generator, there are also various editors and IDE plug-ins to create previews of the specification on the fly. I currently use plug-ins for <a href="https://github.com/asyncapi/vs-asyncapi-preview" target="_blank">Visual Studio</a>  and <a href="https://github.com/Pakisan/jasyncapi-idea-plugin" target="_blank">IntelliJ</a> .</p><p>In addition to HTML, we also have the option of generating a corresponding document in Markdown, for this we only need to use the Markdown template and we get the following result.</p>

```highlight
# Order Service 1.0.0 documentation

The service is in charge of processing orders
## Table of Contents

* [Servers](#servers)
* [Channels](#channels)

## Servers

### **rabbitmq** Server

| URL | Protocol | Description |
|---|---|---|
| localhost:5672 | amqp 0.9.1 | RabbitMQ |

## Channels

### **order-processed** Channel

#### `publish` Operation

Payload of processed order

##### Message

*Inform about a new processed order in the system*

###### Payload

| Name | Type | Description | Accepted values |
|---|---|---|---|
| id | integer | ID of received order | _Any_ |
| customerReference | string | Reference for the customer according the order | _Any_ |

> Examples of payload _(generated)_

```json
{
  "id": 0,
  "customerReference": "string"
}
```



#### `subscribe` Operation

Payload of processed order

##### Message

*Inform about a new processed order in the system*

###### Payload

| Name | Type | Description | Accepted values |
|---|---|---|---|
| id | integer | ID of received order | _Any_ |
| customerReference | string | Reference for the customer according the order | _Any_ |

> Examples of payload _(generated)_

```json
{
  "id": 0,
  "customerReference": "string"
}
```
```

<h3>Extending the documentation process with docToolchain</h3><p>We can add the generated document to the existing architecture documentation in an extended docs-as-code toolchain with <a href="https://github.com/docToolchain/docToolchain" target="_blank">docToolchain</a> . To do this, we run the generation command <code>ag</code> with other parameters.</p>

```highlight
❯ ag -o /Users/danielkocot/doc-showcases/src/docs order-service.yaml @asyncapi/markdown-template -p outFilename=order-service.md


Done! ✨
Check out your shiny new generated files at /Users/danielkocot/doc-showcases/src/docs.
```

<p>Now we find the specification in our architecture documentation folder. Using docToolchain we can convert the Markdown file into the AsciiDoc format as a first step. I use version <a href="https://github.com/docToolchain/docToolchain/releases/tag/v2.0.0" target="_blank">2.0.0</a>  for this, which has been released recently. Version 2.0.0 also introduces a CLI that facilitates the use of docToolchain. The call looks like this.</p>

```highlight
➜ ./dtcw exportMarkdown
dtcw - docToolchain wrapper V0.22
docToolchain V2.0.0
Java Version 11
docker available
home folder exists
use local homefolder install /Users/danielkocot/.doctoolchain/

> Configure project :
arc42/arc42.adoc

BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed
```

<p>The converted file is available in the <code>Build</code> folder and can be incorporated from there into other AsciiDoc(tor) documents via <code>include</code>. This way we ensure that the specifications can be accessed in the process of creating an overall documentation.</p><h2>Summary</h2><p>We have seen that AsyncAPI opens up a possibility to make an event- or message-driven system understandable in a description language that can be read by humans and machines. In contrast to OpenAPI, however, the backend is known when writing the specification so that the peculiarities of the respective system can be addressed. Despite a version number greater than 1, the AsyncAPI spec is still under development. The tooling in the area of code generation is also currently still manageable, but is growing steadily. In connection with docToolchain, there are further possibilities with regard to integration into existing documentation. All in all, this is a very exciting topic that I will be coming back to time and again in the upcoming period.</p>

AsyncAPI – Documentation of event- and message-driven architectures

<p>In our projects we rely on documentation, even if many people still assume that because of the Agile Manifesto documentation is no longer needed ;).<br /> As far as tooling (in terms of documentation) is concerned, we very often use Confluence in projects. This tool provides a lot of possibilities for integration into the documentation process due to a large number of plugins. Whereby a wiki is actually always the last step in a documentation chain, since it is in the classic sense a knowledge base and not a real project-related living documentation. In recent years, the “docs-as-code” movement has become more and more popular. This is about keeping documentation close to the development sources and making it available based on lightweight markup languages, such as <a href="https://www.markdownguide.org">Markdown</a>  and <a href="https://asciidoctor.org" target="_blank">Asciidoc(tor)</a> . And it is precisely this “docs-as-code” that is also increasingly becoming part of products and platforms such as Gitlab and Azure DevOps. Azure DevOps even takes a new approach here. A wiki is provided on the basis of a Git repository. The content can be created using Markdown. With this wiki, we now have a first possibility to establish “docs-as-code” in a project. Azure goes a small step further and extends “docs-as-code” with the integrated <a href="https://mermaid-js.github.io/mermaid/" target="_blank">Mermaid</a>  by “diagrams-as-code”.<br /> With “diagrams-as-code”, we are enabled to create diagrams within a repository and have them versioned with the help of a DSL.</p><h2>Mermaid</h2>

```highlight
sequenceDiagram
    loop Daily query
        Alice->>Bob: Hello Bob, how are you?
        alt is sick
            Bob->>Alice: Not so good :(
        else is well
            Bob->>Alice: Feeling fresh like a daisy
        end

        opt Extra response
            Bob->>Alice: Thanks for asking
        end
    end
```

<p>Well, that is good so far. Unfortunately, Microsoft has not managed to update to the latest version of Mermaid for almost two years (<a href="https://developercommunity.visualstudio.com/t/mermaid-support-for-class-diagrams-and-state-diagr/883356" target="_blank">Developer Community</a> ). So we can’t use the latest features of Mermaid, we only have the option of flowcharts, sequence charts or gant charts to choose from.</p><h2>PlantUML</h2><p>Since I regularly work with entity-relationship models in my current project and usually rely on <a href="https://plantuml.com/de/" target="_blank">PlantUML</a>  for the representation, I wanted to use this again.</p>

```highlight
@startuml

' hide the spot
hide circle

' avoid problems with angled crows feet
skinparam linetype ortho

entity "Entity01" as e01 {
  *e1_id : number <<generated>>
  --
  *name : text
  description : text
}

entity "Entity02" as e02 {
  *e2_id : number <<generated>>
  --
  *e1_id : number <<FK>>
  other_details : text
}

entity "Entity03" as e03 {
  *e3_id : number <<generated>>
  --
  e1_id : number <<FK>>
  other_details : text
}

e01 ||..o{ e02
e01 |o..o{ e03

@enduml
```

<p>Unfortunately, a direct integration into the Azure DevOps Wiki is currently not planned for PlantUML. We now need to find a solution that helps us to fully comply with the “docs-as-code” approach. Since “docs-as-code” is basically based on a pipeline, we will try to generate the graphics and diagrams in exactly this way. Since PlantUML is delivered as a JAR, we need to provide a corresponding runtime environment for the pipeline. This is done in the form of a Docker image which we then make available as a container within the pipeline. You can find the corresponding image in the <a href="https://hub.docker.com/r/codecentric/plantuml-docker" target="_blank">Docker Hub</a> . In the <a href="https://github.com/codecentric/plantuml-docker" target="_blank">Git repo</a>  you can also find the following Dockerfile, which is the basis of the image:</p>

```highlight
FROM docker.io/alpine:3
LABEL maintainer="Daniel Kocot <daniel.kocot@codecentric.de>" \
      description="Internal Docker image for PlantUML"

ENV PLANTUML_VERSION 1.2021.16

RUN apk update
RUN apk add --no-cache graphviz openjdk8-jre curl ttf-droid
RUN mkdir /app
RUN curl -L https://sourceforge.net/projects/plantuml/files/plantuml.${PLANTUML_VERSION}.jar/download -o /app/plantuml.jar
RUN apk del curl

ENTRYPOINT [ "java", "-jar", "/app/plantuml.jar" ]
```

<h2>Azure DevOps</h2><p>Now we can create a repository in Azure DevOps that will contain the sources for graphics and diagrams. In this repository, there must be a <code>plantuml</code> folder. Now we need to create a pipeline for this repo, which basically converts all <code>.puml</code> files in the <code>plantuml</code> folder to PNG format on pushes to the repo. Subsequently, after moving the PNG files to a default build directory, they are published as an artifact using the UniversalPackages task as a package. In Azure DevOps, artifacts can be reused inside and outside projects by using a package feed.</p>

```highlight
trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- script: docker run -v $(Build.Repository.LocalPath)/plantuml:/plantuml --rm -i codecentric/plantuml-docker:1.2021.16 plantuml/*.puml -w /plantuml -o ./output
  displayName: Export PlantUML diagrams

- task: CopyFiles@2
  displayName: 'Copy generated PNGs by PlantUML'
  inputs:
    SourceFolder: './plantuml/output'
    Contents: '*.png'
    TargetFolder: '$(Build.ArtifactStagingDirectory)'
 
- task: UniversalPackages@0
  displayName: 'Publish PlantUML images'
  inputs:
    command: publish
    publishDirectory: '$(Build.ArtifactStagingDirectory)'
    vstsFeedPublish: '<NameofAzureDevOpsProject>/PlantUML-Images'
    vstsFeedPackagePublish: 'plantuml-images'
    packagePublishDescription: 'PlantUML Images'
```

<p>At this point, we can use the feed to check in the automated PNG files to the wiki repository via <code>git</code>.</p>

```highlight
pool:
  vmImage: ubuntu-latest
 
steps:
- checkout: self
  persistCredentials: true
 
- task: CmdLine@2
  inputs:
    script:   git switch -c plantuml-images
- task: UniversalPackages@0
  displayName: 'Download PlantUML images'
  inputs:
    command: download
    downloadDirectory: '$(Build.SourcesDirectory)/plantuml-images'
    vstsFeed: '<NameofAzureDevOpsProject>/PlantUML-Images'
    vstsFeedPackage: 'plantuml-images'
    vstsPackageVersion: '*'
 
- task: CmdLine@2
  inputs:
    script: |
      git config --global user.email <user.email>
      git config --global user.name "<user.name>"
      git pull
      git add .
      git commit -m "added PNGs generated by PlantUML"
      git push --set-upstream origin plantuml-images
  displayName: Adding PNGs by using GIT
```

<p>A new branch <code>plantuml-images</code> is being created by the push. Subsequently, this must be merged with the main branch via a pull request. This allows us to include the PNG files within the wiki supported by the Azure DevOps API (<code>https://dev.azure.com/<organizationName>/<projectId>/_apis/git/repositories/<area>/items?path=/plantuml-images/<image-name>.png</code>) and the <code>img</code> HTML tag.</p><h2>Conclusion</h2><p>This blog post describes a way to integrate PlantUML with the Azure DevOps Wiki. Even though the integration requires a lot of knowledge about Azure DevOps, it is still a very simple solution, but can also be extended in terms of linking build pipelines.</p>

Getting project documentation done with Azure DevOps – Diagrams with PlantUML

From specification to infrastructure – automated API deployments

<p>Almost six months have passed since my <a href="https://blog.codecentric.de/en/2021/09/asyncapi-documentation-event-message-driven-architectures/">introductory post about AsyncAPI</a> , which is already an eternity in our fast-moving IT world. 😉 Shortly after publishing said post, more precisely in September last year, version 2.2.0 of the specification was released. At the beginning of February this year there was another so-called minor release to AsyncAPI version 2.3.0. Both versions are backward compatible with regard to the written API description, so that an update of the existing version value for the key <code>asyncapi</code> shouldn’t be a problem and the description is still valid afterwards.<br /> I would also like to use the previously used description again, which has been optimized a bit in the meantime, and use it to perform the migrations to version 2.3.0 of the specification.</p>

```highlight
asyncapi: '2.1.0'
info:
  title: Order Service
  version: 1.0.0
  description: The service is in charge of processing orders
  contact:
    name: Daniel Kocot
    email: daniel.kocot@codecentric.de
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  rabbitmqInStaging:
    url: rabbitmq-staging.codecentric.de:{port}
    description: RabbitMQ Broker in staging environment
    protocol: amqp
    protocolVersion: '0.9.1'
    variables:
      port:
        default: '5672'
        enum:
          - '5672'
          - '15672'
  rabbitmqInProd:
    url: rabbitmq.codecentric.de:{port}
    description: RabbitMQ Broker in production environment
    protocol: amqp
    protocolVersion: '0.9.1'
    variables:
      port:
        default: '5672'
        enum:
          - '5672'
          - '15672'
channels:
  orderProcessed:
    publish:
      operationId: orderProcessedPub
      description: Payload of processed order
      message:
        $ref: '#/components/messages/orderProcessed'
      bindings:
        $ref: '#/components/messageBindings/amqp/bindings'
    subscribe:
      operationId: orderProcessedSub
      description: Payload of processed order
      message:
        $ref: '#/components/messages/orderProcessed'
      bindings:
        $ref: '#/components/messageBindings/amqp/bindings'
    bindings:
      amqp:
        $ref: '#/components/channelBindings/amqp'
components:
  schemas:
    OrderPayload:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ID of received order
        customerReference:
          type: string
          description: Reference for the customer according the order
  messages:
    orderProcessed:
      name: orderProcessed
      title: Order Processed
      summary: Inform about a new processed order in the system
      contentType: application/json
      payload:
        $ref: '#/components/schemas/OrderPayload'
  channelBindings:
    amqp:
        is: routingKey
        exchange:
          name: orderExchange
          type: direct
          durable: true
          vhost: /
        bindingVersion: 0.2.0
  messageBindings:
    amqp:
      bindings:
        amqp:
          timestamp: true
          ack: false
          bindingVersion: 0.2.0
```

<h2>Assigning channels to servers</h2><p>Let’s start directly with the first feature, the assignment of channels to servers, which has been available since AsyncAPI 2.2.0. This enables us to assign the respective channel to one or more specific servers. This is done by setting the optional <code>servers</code> property of type string related to the <code>Channel Item</code> object. Please note that the names of the servers always need to be the same as the names of the servers defined in the <code>server</code> object. We now adapt the above example to the feature accordingly.</p>

```highlight
asyncapi: '2.2.0'
info:
  title: Order Service
  version: 1.0.0
  description: The service is in charge of processing orders
  contact:
    name: Daniel Kocot
    email: daniel.kocot@codecentric.de
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  rabbitmqInStaging:
    url: rabbitmq-staging.codecentric.de:{port}
    description: RabbitMQ Broker in staging environment
    protocol: amqp
    protocolVersion: '0.9.1'
    variables:
      port:
        default: '5672'
        enum:
          - '5672'
          - '15672'
  rabbitmqInProd:
    url: rabbitmq.codecentric.de:{port}
    description: RabbitMQ Broker in production environment
    protocol: amqp
    protocolVersion: '0.9.1'
    variables:
      port:
        default: '5672'
        enum:
          - '5672'
          - '15672'
channels:
  orderProcessed:
    servers:
      - rabbitmqInStaging
    publish:
      operationId: orderProcessedPub
      description: Payload of processed order
      message:
        $ref: '#/components/messages/orderProcessed'
      bindings:
        $ref: '#/components/messageBindings/amqp/bindings'
    subscribe:
      operationId: orderProcessedSub
      description: Payload of processed order
      message:
        $ref: '#/components/messages/orderProcessed'
      bindings:
        $ref: '#/components/messageBindings/amqp/bindings'
    bindings:
      amqp:
        $ref: '#/components/channelBindings/amqp'
components:
  schemas:
    OrderPayload:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ID of received order
        customerReference:
          type: string
          description: Reference for the customer according the order
  messages:
    orderProcessed:
      name: orderProcessed
      title: Order Processed
      summary: Inform about a new processed order in the system
      contentType: application/json
      payload:
        $ref: '#/components/schemas/OrderPayload'
  channelBindings:
    amqp:
        is: routingKey
        exchange:
          name: orderExchange
          type: direct
          durable: true
          vhost: /
        bindingVersion: 0.2.0
  messageBindings:
    amqp:
      bindings:
        amqp:
          timestamp: true
          ack: false
          bindingVersion: 0.2.0
```

<h2>Servers and channels as reusable objects</h2><p>With version 2.3.0 <code>servers</code> and <code>channels</code> are available as reusable objects. Thus, the two elements only have to be defined within the <code>components</code>, then they can be referenced within the description. This is now also applied to our example description.</p>

```highlight
asyncapi: '2.3.0'
info:
  title: Order Service
  version: 1.0.0
  description: The service is in charge of processing orders
  contact:
    name: Daniel Kocot
    email: daniel.kocot@codecentric.de
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  staging:
    $ref: '#/components/servers/rabbitmqInStaging'
  production: 
    $ref: '#/components/servers/rabbitmqInProd'
channels:
  orderProcessed:
    servers:
      - staging
    publish:
      operationId: orderProcessedPub
      description: Payload of processed order
      message:
        $ref: '#/components/messages/orderProcessed'
      bindings:
        $ref: '#/components/messageBindings/amqp/bindings'
    subscribe:
      operationId: orderProcessedSub
      description: Payload of processed order
      message:
        $ref: '#/components/messages/orderProcessed'
      bindings:
        $ref: '#/components/messageBindings/amqp/bindings'
    bindings:
      amqp:
        $ref: '#/components/channelBindings/amqp'
components:
  schemas:
    OrderPayload:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ID of received order
        customerReference:
          type: string
          description: Reference for the customer according the order
  servers:
    rabbitmqInStaging:
      url: rabbitmq-staging.codecentric.de:{port}
      description: RabbitMQ Broker in staging environment
      protocol: amqp
      protocolVersion: '0.9.1'
      variables:
        port:
          default: '5672'
          enum:
            - '5672'
            - '15672'
    rabbitmqInProd:
      url: rabbitmq.codecentric.de:{port}
      description: RabbitMQ Broker in production environment
      protocol: amqp
      protocolVersion: '0.9.1'
      variables:
        port:
          default: '5672'
          enum:
            - '5672'
            - '15672'
  messages:
    orderProcessed:
      name: orderProcessed
      title: Order Processed
      summary: Inform about a new processed order in the system
      contentType: application/json
      payload:
        $ref: '#/components/schemas/OrderPayload'
  channelBindings:
    amqp:
        is: routingKey
        exchange:
          name: orderExchange
          type: direct
          durable: true
          vhost: /
        bindingVersion: 0.2.0
  messageBindings:
    amqp:
      bindings:
        amqp:
          timestamp: true
          ack: false
          bindingVersion: 0.2.0
```

<h3>Contributor time</h3><p>When looking at the description, it quickly becomes apparent that there is further potential with regard to reusability. This refers specifically to the <code>variables</code> for the <code>server</code> object. Exactly this caused me to post a <a href="https://github.com/asyncapi/spec/issues/707" target="_blank">Request for Comments (RFC)</a>  in the Git repo for the specification. In the meantime three pull requests followed out of the RFC. One for the <a href="https://github.com/asyncapi/spec/pull/717" target="_blank">specification</a>  itself and the other for the <a href="https://github.com/asyncapi/spec-json-schemas/pull/174" target="_blank">JSON schema</a> . I submitted the third and final pull request for the <a href="https://github.com/asyncapi/parser-js/pull/476" target="_blank">JS parser</a>  shortly after the post was published. Now the feature can become a part of the next release (2.4.0) of the AsyncAPI specification. Hopefully ;). If you also have a feature in mind for an open-source project, I can only encourage you to put it into action. Only in this way can we help keep open source an integral part of our daily work.</p><h2>New protocol bindings</h2><p>After this short trip into the world of open source contributions I would like to take a look at the innovations regarding protocol bindings. What is actually meant by protocol bindings? Protocol bindings or short bindings describe the specifics of the used protocol. They are the basis of the architecture component, which is an essential part of the description with AsyncAPI. This can be done on the levels of <code>server</code>, <code>channel</code>, <code>operation</code> and <code>message</code>. Up to version 2.1.0 the following protocols are supported:</p><ul><li>HTTP</li><li>Websockets</li><li>Kafka</li><li>AMQP 0.91</li><li>AMQP 1.0</li><li>MQTT</li><li>MQTT 5</li><li>NATS</li><li>JMS</li><li>SNS</li><li>SQS</li><li>STOMP</li><li>Redis</li><li>Mercure</li><li>IBM MQ</li></ul><p>However, the binding for IBM MQ cannot be applied at the level of ‘operation’. With the last two releases two more bindings for Anypoint MQ and Solace have been added. More detailed information about the bindings can be found at <a href="https://github.com/asyncapi/bindings" target="_blank">Repo</a>  within the AsyncAPI Org in GitHub.</p><h2>Outlook and summary: Beyond AsyncAPI version 2.3.0</h2><p>In AsyncAPI, we find a very convenient way to describe event- and message-driven architectures and also to incorporate this description into existing processes of our API lifecycle, supported by CI/CD pipelines. It will be exciting to see how this and other specifications and the topics around the description of APIs will evolve in the coming years. So look forward to more posts on these aspects.</p>

AsyncAPI specification updates

API Experience – How API products get ready for digital markets

<p><span>Currently, platform engineering is a topic that is causing a lot of reactions in the vastness of the World Wide Web. Especially for customers from the enterprise environment, it leads to interesting side effects when DevOps teams suddenly turn into Platform Engineering teams. With this blog post, I would like to demystify the wording and show possibilities that arise from it.</span></p><p><span>But first, let’s go back a few years in codecentric’s history. To be more precise, to the year 2014. At that time, we had the idea of the Agile Software Factory, which was supposed to  enable teams to quickly implement the idea of a software product. This includes the implementation of an entire toolchain for software development. In this way, we were already indirectly addressing topics such as developer experience and governance, without naming them specifically. Thus, deliverability was established in a relatively short time, at least with regard to a first increment. As I said, that was 2014!</span></p><p><span> </span><span>Nowadays, we are dealing with many tools in the software development lifecycle. Especially in large companies, this leads to a problem, as each department brings its own idea about the software lifecycle into the mix. Consequently, it is worth thinking about unifying this large amount of tools. This leads to the idea of supporting developers with self-service approaches more and more. Over time, companies need more rules and guidelines for the development of products or even a platform. This is precisely the first lever that Platform Engineering would like to apply, in which the developers in a company are offered the opportunity to move along established paths or along a Golden Path, in order to focus again on the original aspect of software development – implementing ideas in a way that can be tested quickly.</span></p><h2><span>Golden Path?</span></h2><p><span>Spotify also took the steps towards the Golden Path in 2014. This shows that codecentric was on the cutting edge with the idea of the Agile Software Factory, but was not yet able to summarize the whole topic into one term. One suspects that Spotify borrowed the term Golden Path from the Dune trilogy. According to the Dune Fandom explanation, the Golden Path represents an optimal path through the countless threads of cause and effect that humanity has encountered. This optimal path was what Spotify was trying to achieve in the spirit of growth at the time, so as not to lose speed in the development of software components. But it’s not about bullying a developer or enforcing standards. Rather, teams shouldn’t have to reinvent the wheel or make fewer decisions. Companies should also set up platform offerings with this in mind: as visible and tangible support for developers.</span></p><p><span>Thus, the idea of the Golden Path is not limited to CI/CD processes, but has the whole chain of deployment processes in the sense of platform engineering in mind, such as </span></p><p><span>– Adding environment variables and changing configurations</span></p><p><span>– Adding services and dependencies</span></p><p><span>– Rollback and debugging </span></p><p><span>– Setting up a new environment</span></p><p><span>– Adding/changing resources</span></p><p><span>– Implementing role-based access control</span></p><p><span>However, the focus here is always on the self-service aspect. This leads to an Internal Developer Platform, which, according to Evan Bottcher, is “a foundation of self-service APIs, tools, services, knowledge and support.” Such a platform is a corresponding second vector of platform engineering, which is now being used by a number of manufacturers. </span></p><p><span>A look at the tool landscape around platform engineering shows that two products are currently very present in the market: Backstage and Humanitec. In his last blog post, my colleague Jonas presented another tool, Crossplane, which I will not discuss in detail in this post.</span></p><h2><span>Backstage</span></h2><p><span>Spotify has developed Backstage and made it available to the market as an open source product. However, as my colleague Pascal Sochaki has said,, Backstage should be understood more as a framework that enables companies to deliver a front-end to their internal development platform. For this purpose, Backstage offers the possibility of providing software components through software templates. In concrete terms, this means that a Git repo including Docker and pipeline files is created. After successful deployment, the component is then listed in Backstage. In addition, the framework can be extended by plugins to include further functionalities, also with regard to the visibility of the deployment.</span></p><h2><span>Humanitec</span></h2><p><span>In comparison to Backstage, Humanitec sees itself as a platform orchestrator and thus as the central unit of an Internal Developer Platform. It represents the basis for dynamic configuration management, which is described by the manufacturer as a Declarative Application Model. This model describes the workload of a deployment as agnostically as possible. A basis for this kind of the description develops straight with the Platform Agnostic Workload Specification (PAWS). </span></p><p><span>With Backstage, Humanitec and Crossplane, we now see different tools in the context of platform engineering. Their effectiveness is limited to visibility on the one hand and deployment orchestration of services on the other. But exactly these two points should be automated within the work of a developer and also the automation should be done in a simple way. Thus, these mentioned tools show a representative way to an Internal Developer Platform, which can guarantee the often mentioned Developer Experience.</span></p><h2><span>Conclusion</span></h2><p><span>Platform Engineering is thus not really a new idea, but rather considers the processes around CI/CD in the development of software end-2-end. Likewise, it is also about creating a kind of uniformity in terms of the tool landscape, the components and their corresponding use. This also requires communication between individuals and teams. </span></p><p><span>Let’s feel free to discuss this- What is your understanding of platform engineering? What are you already doing? What would you like to adapt to your situation?</span></p><p> </p>

Platform Engineering – A primer

<h2>Approaches for API consumers</h2><p><em>“We do know our consumers. We know exactly what they want.” Very often I hear these two sentences at the beginning or in the middle of projects. But who is a consumer of an API or a digital product in the fist place?</em></p><p>This is a question that should be on every API provider’s mind whenever the team is adopting <a href="https://blog.codecentric.de/en/2020/09/api-as-a-product-insights/">API as a Product</a> . It doesn’t matter if it’s internal or external. In this article, I will takle <a href="https://blog.codecentric.de/en/2022/06/api-experience-how-api-products-get-ready-for-digital-markets/">API Experience</a>  from the consumer’s perspective. We have developed a methodology for the vendor that addresses consumer needs – but does it really meet them? Because we know that API consumers always finds themselves somewhere in the middle between search and feedback.</p><p><img width="1024" height="683" src="https://media.graphassets.com/pusYHsCoTEOh18sLuozy" alt="API Management" /><br /> If we now take a look at the API management process (see figure above), a consumer may go through the following phases:</p><ul><li>Discover</li><li>Develop</li><li>Consume</li><li>Monitor/Optimize</li></ul><p>All four phases have in common that a consumer has the chance to give feedback at any time. If you take a closer look at the phases, you also get the impression that the use of a platform will be of great importance for the cycle “Discover – Develop – Consume”. But then who are actually the users of such a platform?</p><h3>Personas</h3><p>In general, we encounter two types of consumers and simultaneous users of a platform. On the one hand, there is the business, also often referred to as the department. On the other hand, there is a developer persona. This type can be found in the following forms in teams:</p><ul><li>Enterprise Developer</li><li>Web Developer</li><li>Device Developer</li><li>Data Scientist</li></ul><p>Basically, they are all share a basic habit of finding the data they are looking for in the form of a good interface, the API. However, business is now increasingly taking over the role of a developer. In the literature, the term Citizen Developer is used to characterize this role. By Citizen Developer we mean a person from the business who can create applications without programming knowledge, but usually with the support of the IT department. Thus, we are now dealing with three different consumers:</p><ul><li>the business</li><li>the Citizen Developer</li><li>the developer, as the classic user of an API</li></ul><h3>API Interaction Patterns</h3><p>In order to understand consumers’ needs, it is important for a comprehensive API experience that we complete it on an abstract level without drifting too much into the technologies.<br /> To achieve this, we generally make use of patterns in software development. With API Interaction Patterns we can do this with regard to the description of APIs. The following patterns are currently used in projects around APIs.</p><p><strong>Tunnel</strong><br /> The idea of Tunnel Pattern goes back to ideas like Remote Procedure Call (RPC). From a developer’s point of view, it’s a convenient way to provide simple extensions for existing procedures for the purpose of exchange. But the handling around the tunnel, i.e. the technical access to the respective endpoint, makes it difficult for the consumer to use. This led to the availability of a simpler protocol for the tunnel in the form of HTTP and consequently to a proliferation of APIs based on the Resource Pattern.</p><p><strong>Resource</strong><br /> The consumer-oriented approach is the focus of the resource pattern as opposed to the tunnel. Basically, it is about making the appropriate resources accessible that consumers use so that interaction can take place starting with the consumer. In this way, there is an opportunity to hide any implementation details behind the resources. But the resources sometimes do not contribute to an improved representation, because it is not possible to show relations between the resources without additional processes or workflows. This is exactly the problem the Hypermedia Pattern wants to solve.</p><p><strong>Hypermedia</strong><br /> The Hypermedia Pattern builds on the Resource Pattern and adds the use of links to it. As with the web, the paths between resources can be navigated by links between them, without having to know each individual resource. Thus, a consumer receives a lot of information, of which one does not know at the moment whether one really needs it. It already contributes to the fact that such an API is regarded as “chatty”. However, what should actually be achieved can be solved in another way: with the Query Pattern.</p><p><strong>Query</strong><br /> While with the Resource style we face one endpoint per resource, with the Query style it is only one endpoint where the consumer is enabled to query the resources behind the API. The consumer also gets back exactly the result that matches their query. This in turn means that there must be a good knowledge of the data as well as the query models on the consumer side.<br /> If we now look at the styles shown so far, we see that they are all based on the same assumption. The consumer is the trigger of the interaction by sending a request and then waiting for a response.<br /> What does it actually look like if the consumer wants to be informed about every change and does not need to explicitly request?</p><p><strong>Event-Based</strong><br /> This is where the Event-Based Pattern comes into play. With this interaction pattern, the Publish/Subscribe Pattern (PubSub) also makes its way into the infrastructure. Based on events, consumers and producers can be connected directly or a message broker is located between the two for some decoupling. Unlike the other styles, we now find a kind of centralized architecture.</p><h3>On search and retrieval</h3><p>The Interaction Patterns now form the basis that API providers need to describe the APIs to be provided, including the data models. Here we talk about <a href="https://developers.google.com/protocol-buffers/docs/reference/proto3-spec" target="_blank">ProtoBuf</a> , <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank">OpenAPI</a> , <a href="https://spec.graphql.org/October2021/" target="_blank">GraphQL schema</a> , <a href="https://www.asyncapi.com/docs/reference" target="_blank">AsyncAPI</a>  and <a href="https://json-schema.org/specification.html" target="_blank">JSON schema</a> , among others. By describing a respective API and the data model, it is ensured that “search and find” becomes possible at any time.<br /> The Discover phase represents the main interest of API consumers, so that they, too, can always explore further digital business areas. However, the creation of a description represents a sufficient criterion. To support discovery, it is now necessary as a provider to ensure the storage of descriptions. In general, we are talking about a catalog that makes it possible to guarantee access to descriptions. At this point, I usually hear in conversations with customers that they need an API gateway for this. An API gateway does not support the consumer here, but is intended to help with the general provisioning of APIs at the vendor. But why does this misconception occur?<br /> There are several reasons. First, almost every API gateway provides a portal as part of API management. Second, vendors state that an API gateway contributes to the visibility to the consumer, but this is completely false. An API gateway can contribute to visibility of APIs, but in order to support search and discovery, more is required.<br /> The simplest form is a catalog. A second step would be a portal. The portal can be seen as a separate component next to an API gateway and thus becomes a part of the infrastructure as well. Thus, Configuration as Code comes into play here too. As consumers, we are enabled to understand the API products consisting of API definition and data model in an almost textual way. However, it is also possible to offer a common portal for several API gateways.<br /> The next level, starting from a portal, is a hub. It should be understood more as a comprehensive umbrella for complex architectures. The picture of the umbrella shows that a hub can also be a first step towards an Internal Developer Platform. The Internal Developer Platform is a part of Platform Engineering, whose goal is to achieve the best possible developer experience for the entire development process.<br /> The fourth and final stage is the registry. We are already familiar with the concept of a registry, namely storing and making accessible in an audited manner, from the context of event-based systems. In the context of APIs, it is primarily a matter of storing artifacts such as API definitions and associated data model schemas. Compared to a hub, the registry is a very technical component, characterized primarily by the use of the interface in the form of REST. A prominent representative here is the <a href="https://www.apicur.io/registry/" target="_blank">Apicurio Registry</a> . Likewise, the registry supports the concept of an Internal Developer Platform.</p><p>What all the presented stages have in common is that they create a desire among consumers for semantic search to significantly enhance the experience in terms of searching and retrieval. But what exactly is meant by semantic search in our context? The term describes a search method that focuses on the meaning of a query.</p><p>In our context, this means that consumers are searching for a data model and need a direct link to possible APIs. The idea of a direct search for an API originates from a time when a developer’s persona was seen as the only consumer. Similarly, it is worthwhile at this point to show a possible link between an explicit (external) and a global data model. We now see that the desire for a semantic search for the API provider side is not a simple undertaking and already goes far beyond the concrete representation. At the same time, we are creating a transition to Developer Experience.</p><h3>Mythical DX</h3><p>In the context of APIs and consumers, the term Developer Experience quickly comes up and is often used as a way to advertise software products. But what does it mean specifically?</p><p>Developer Experience describes a developer’s expectation of a platform, and it’s not primarily about the form of delivery, but the overall experience. This includes communication options with the API provider, well-designed deployment and billing processes. Regarding the types of developers outlined above, we also still need to incorporate different gradations to really bring about the same experience for everyone. But especially in the context of API as a Product, the business also needs a corresponding understandable experience, as the requirements are not comparable to those of a developer.<br /> The business or even the Citizen Developers are usually driven by data and use APIs only as a technical vehicle to obtain the desired data. Therefore, it is important to also give high priority to the data model that an API will deliver in terms of documentation. If we now look at the big picture from the perspective of an API provider, we need multiple views of the data and also the API description so that they can be effective in terms of their target group. In other words, this means that the classic API portal, which usually comes with an API gateway, cannot be effective with respect to the relevant target groups apart from developers. Looking at data models, we come across so-called Data Catalogues. This form of cataloging is meant to satisfy the rules of compliance and governance. Thus, the platform idea is expanded by another component and now clearly shows that the provision of APIs cannot only be done on the basis of a standard solution.</p><h3>Conclusion</h3><p>In order to obtain a real end-to-end API experience, many components are needed, but above all, communication. In the end, it requires mature solutions or a platform that accompanies consumers on their entire developer journey.</p>

API consumers – between search and feedback

So far, I've focused on the API design phase in posts and articles published. But a well elaborated API design is only one building block for a balanced API experience in terms of API consumers. Architecture topics represent another important building block. In the API community, the term "API architecture" pops up time and again. But what exactly is meant by it?

## API architecture?

For many, "API architecture" is probably just another word creation. This neologism is gaining importance as system architectures become more and more complex. In the context of APIs, we are moving in the context of evolutionary architectures. When did software and system architectures become evolutionary and what exactly does this mean? Evolutionary architectures should and may develop over time. They are a concept that was thought up by Rebecca Parsons and Neal Ford [Building Evolutionary Architectures, O'Reilly 2018]. Architectures around APIs fit right into this concept, as the ultimate goal is, after all, to design and develop APIs in such a way that proper changes can be made for ease of use without causing breaks in use, known as breaking changes, on the part of consumers. To accomplish this, we now need an abstraction layer. This is important so that we don't get lost in technologies on both the provider and consumer side. An adequate aid here is patterns with which any kind of architecture can be abstracted.

## Use of patterns

In the context of APIs, the following three kinds of patterns are interesting for us; Facade / Adapter, Strangler Fig and the API Layer Model. I will now describe these in more detail below and classify them in terms of usefulness.

### Facade / Adapter

These two patterns are basically mentioned first in the context of a migration to a new service structure, mostly in the form of microservices, and are very similar, even though a Facade is less complex compared to an Adapter. The latter presupposes the respective architecture around a so-called component, which could carry out a protocol conversion, for example. The history of both goes back to the Gang of Four and the patterns were revived in Richardson's Microservice Pattern in the form of the Gateway Pattern.

### Strangler Fig

The Strangler Fig pattern is basically a kind of a facade that, roughly speaking, intercepts the API requests and continues to shield the respective query complexity for consumers. In terms of evolutionary architectures, this means that the Strangler Fig Pattern supports an existing system to change. This is achieved by adding a new component while something existing is still present and in use. The goal is now to gradually move to a new approach, but without a consumer of the service or API noticing a change in the backend.

### API Layer Pattern

If we now look at it more from an enterprise context, we are confronted with an API Layer Pattern. Unfortunately, this was and still is a general practice from which vendors of solutions in the integration context do not shy away either. The idea behind the pattern is actually quite simple, as all communication should go through the respective layers. But these layers can create a high level of coupling, which can then lead to duplicates again in order to bypass the call of a specific layer. Thus, a high complexity can also go along with it.

In view of evolutionary systems, it remains to be stated that the use of the API Layer Pattern in comparison to Strangler Fig does not contribute necessarily to the development speed and security of such a system. 

## API management solutions as a must-have tool?

Even if one does not exactly think and plan in evolutionary architectures now, many still try to find their salvation in API management solutions. According to vendors, this is a must-have for anyone who wants to develop and deploy APIs. But the introduction of an API management solution, an API gateway or even a service mesh  only makes really sense if the first API services have already been developed and the respective teams understand that the aforementioned components help them to develop further with APIs into the evolutionary architectures already mentioned. After all, API management solutions are not an end in themselves, but rather support existing processes. This is exactly where we come full circle with topics pertaining to API Operations (<a href="https://blog.codecentric.de/apiops-deployment-api-definitions" target="_blank">APIOps</a>).

## Conclusion
When we think about APIs and architectures, we need to pause for a moment and ask ourselves what specifically we actually want to achieve with APIs that have been created or are yet to be created. Only then can we make initial decisions regarding a possible architecture. In the end, it must be clear that this architecture does not necessarily have a long life and we therefore need a high degree of flexibility, which providers of a large ready-made solution cannot necessarily guarantee.

API architecture – The path towards evolutionary architectures

Having learned in <a href="https://medium.com/@daniel.kocot/designing-apis-is-very-hard-work-744a37ff13ad" target="_blank">one of my posts on Medium</a> that API design is not really an easy task and involves a lot of work, also mentioned in my <a href="https://blog.codecentric.de/api-architecture-path-towards-evolutionary-architectures" target="_blank">last post</a> here on the blog, I'm going to move on to another complicated area of APIs, APIOps and, in more detail, the deployments of API definitions. Some readers may be wondering why, as there is already a <a href="https://blog.codecentric.de/apiops-automated-processes-for-even-better-apis" target="_blank">post</a> of mine on the blog about APIOps from January 2021. Since the latter was written at a different level of depth, it is time to revisit the implementation of APIOps. 
 
## APIOps, what does that  mean exactly?
APIOps denotes a process that prepares API definitions for deployment. This process is supposed ensure that the definitions are valid and tested on the base of the API guideline.

![APIOps_in_Action-final.png](https://media.graphassets.com/whMEmL1jSSrOdW3oJTZ2)

For the use of APIOps, it is basically irrelevant which CI/CD tool is supporting the process. For further consideration, the push of an API definition in the Git repository represents the starting point. With APIOps, we have exactly one goal in terms of deployment: to distribute the API definition artifact to different components or to make components available on the base of the artifact.

![api_deployment.png](https://media.graphassets.com/Umq5D6Z2Sr2mibYHyRDq)

## CI of APIs
Using Continuous Integration (CI), we can achieve this as part of APIOps. We combine all elements of API definitions by building, which means joining references within a definition, for validation and testing.

### Build
An API definition can be created from different sub-documents by using the *ref* property. For the following steps it is important that we have a merged API definition in which the respective references are resolved. This can be easily achieved using the `join`-command of <a href="https://github.com/Redocly/redocly-cli" target="_blank">redocly-cli</a>.

### Validate
In the _Validate_ stage, the terms _Linting_ and _Validation_ are often used. Therefore, I would like to clarify the difference between _Linter_ and _Validator_ in advance. A linter looks for suspicious or dangerous code and validates the code against design guidelines. A linter must be able to parse the code, which means it also validates against a language specification. This means that, to some extent, a linter is a validator with additional functions. A validator makes sure he code conforms to the language specification. It doesn't care about style or logic. 

The step "_Validate_" can now be done, supported by different tools. Currently <a href="https://stoplight.io/open-source/spectral" target="_blank">Spectral</a> as well as redocly-cli are very visible here. Using redocly-cli has proven to be a good recommendation from the project experience. The supplied rules react more exactly to violations against the OpenAPI specification. With both tools, it is basically a matter of creating rule sets, which can still be extended with your own written functions. Which tool you choose is again a matter of taste. I generally use both in my projects, since I find it easier to create rules in Spectral.

```yaml
extends: spectral:oas
rules:
  contact-properties: info
  include-title:
   description: Info section has to include a title as identifying name of the API.
   given: $.info
   severity: error
   then:
     field: title
     function: truthy
   include-version:
    description: Info section has to include a version following semantic rules.
    given: $.info
    severity: error
    then:
      field: version
      function: truthy
 valid-semantic-version:
    description: Versions are restricted to the format <MAJOR>.<MINOR>.<PATCH>, e.g. 1.0.0. See https://developer.docs.company.net/api/guidelines.html#semantic-versioning for details.
    given: $.info
    severity: error
    then:
      field: version
      function: pattern
      functionOptions:
          match: ^([0-9]+)\.([0-9]+)\.([0-9]+)$
```
Within the CI pipeline, their use is based on the respective command line interface (CLI). However, in order to validate an API definition, it is necessary to have corresponding guidelines for the design of APIs. In the world wide web we find a lot of them. So please adapt them and don't copy them ;). If a set of rules for linting and validation has been developed from the guidelines, a respective API definition can now also be validated accordingly. Exactly this result decides on the progress of the pipeline and thus whether the definition meets the requirements for good APIs within the organization or the company. Good API definitions deserve to be tested afterwards ;).

### Test
When testing APIs, a distinction needs to be made between three different types related to APIs, _Contract_, _Content_, and _Variation_. All three have different goals during testing. Contract testing is about validating the API definition from the consumer's point of view, whereas Content Testing focuses around testing the validation of response values. The previous approaches have always tested for success, the so-called "happy path". But what if exactly this is not desired and we want to check whether the expected answers are also output for any error answers? Then we need to take a look at Variation Testing.

In projects it has proven to be very useful *not* to write down these test procedures in an individual test suite based on frameworks like <a href="https://mochajs.org" target="_blank">mocha</a> and <a href="https://www.chaijs.com" target="_blank">chai</a>, but to describe the respective tests based on a configuration. Within the pipeline, <a href="http://getportman.com/" target="_blank">Portman</a> is used for testing, since it exactly fulfills the requirements.


```json
{
   "version": 1.0,
   "tests": {
                   "contractTests": [],
                   "contentTests": [],
                   "variationTests": [],
   },
   "globals": {
         "stripResponseExamples": true
  }
}
```
By using Portman, a postman collection is created directly after a successfully executed contract test, which in turn is also included in the test. In the previous _Validate_ block, an API definition is created that is resolved by all references. Since this is the basis for the contract test, two tested artifacts can now be delivered to interested consumers.
In addition to the types of tests shown, performance tests are also of interest for APIs. After all, it is important for the respective provider to know how resiliently an API works under load. For this purpose, the created postman collection can be used. With the help of <a href="https://github.com/apideck-libraries/postman-to-k6" target="_blank">postman-to-k6</a>, it is possible to create a <a href="https://k6.io/open-source/" target="_blank">k6</a> script from a collection and execute it with k6. In a following post I will go into more detail about k6. Hence only this short summary for now.

## CD of APIs
The final block of an APIOps pipeline is the deployment to the corresponding target environments. The first question here is whether the API definition can simply be pushed in the direction of the target environment, i.e. the target environment is able to read and process the OpenAPI specification. Additionally, OpenAPI extensions are used for this purpose. However, it may also be that the target environments are to be rolled out on the basis of Configuration as Code (CoC) in the direction of Infrastructure as Code (IaC). In the context of deploying API definitions, using IaC doesn't make it any easier in terms of an API architecture, since the target environments are also infrastructures. At this point, however, I would like to conclude the topic of deployment for now. Due to the complexity, we can see that this phase of an APIOps pipeline must always be considered in relation to the architecture and also the infrastructure.

## Conclusion
We now have to realize that APIOps is not a trivial process that just disappears with a flick of the wrist. Instead, it contains many facets that cannot simply be solved with one tool or one platform.
A short list of the tools used:
- redocly CLI
- Stoplight Spectral
- Portman
- postman-to-k6
- k6

The ideas around APIOps must evolve from within a team. With APIOps, such a team also delivers a segment of the "Golden Path", which is desired by many developers. This is where APIOps also addresses the buzzworthy Developer Experience. But APIOps is not finished with this post, because we currently only have the classic Rest(ful) APIs in mind. We are also not looking at security issues. So we still have to open these doors. Perhaps you already have ideas on how you want to tackle these individual topics? Or do you have alternative tools in your toolbox? I appreciate your comments.

The state of APIOps and the deployment of API definitions

Following last week's launch of a <a href="https://www.linkedin.com/pulse/talking-apis-week-18-daniel-kocot/" target="_blank">new series of articles on LinkedIn</a>, there is now a refresh under a new name on the codecentric blog. Why "Charge your APIs"? Quite simply, we all need to think APIs further and not just see them as a vehicle for integration. But for that, there is a lot to do besides the classic API design. That's why I would like to pick a particular topic each week and look at it in more detail. And I'll also tell you one or two tricks from our everyday project work. And here we go!
Last week's focus was on Any Decision Records (ADRs). The Decision Records served as a starting point. Now, this week, we want to build the foundation for the creation of relevant API guidelines. At this point, I would like to define again what API guidelines actually are.

## Refreshing API-Guidelines
API guidelines are a set of rules and recommendations that should be considered when developing and using APIs. These guidelines can refer to various aspects of API design, such as the naming of endpoints, the use of HTTP methods, the handling of error messages or the documentation of interfaces.

The goal of API guidelines is to increase the consistency and usability of APIs to ensure a better experience for developers and users. Well-designed APIs that follow the guidelines can also contribute to easier maintenance, scalability and integration of applications.

A bit more information on API guidelines can be found in <a href="https://medium.com/@daniel-kocot/api-guidelines-the-lifeline-when-designing-of-apis-93b1a1f8d0ca" target="_blank">my post on Medium</a>.

Now, if we want to create API guidelines, we can do so using any editor and store them in a central location in the organisation. The writing process and storage are only part of the whole. We have already set the textual foundation with ADRs. From them, we now want to create the documentation for our API initiative. In the context of documentation systems, static site generators are becoming more and more common.

## Static Site Generator
A static site generator is a tool used to create static websites. Unlike dynamic websites, which use databases and server-side scripts, static websites generate all pages in advance and store them on the server. The generator uses a template and content in the form of text, images, etc. and generates the static HTML files for the website. Static site generators enable faster and more secure website development, as no server-side processing is necessary and content can be cached more efficiently. They are also great for creating documentation, as in the context of API guidelines, as they make it easier to create and manage content in a central data source.

## Building a documentation system with mkdocs
Today I'd like to take a look at <a href="https://www.mkdocs.org" target="_blank">mkdocs</a>. A very lightweight system based on Python and Markdown. After installing mkdocs, you can start right away.

```yaml
❯ mkdocs new acme-api-initiative
INFO     -  Creating project directory: acme-api-initiative
INFO     -  Writing config file: acme-api-initiative/mkdocs.yml
INFO     -  Writing initial docs: acme-api-initiative/docs/index.md
```

With the creation of the directory for the ACME API initiative, we have laid the foundation. With the possibility of using plugins and templates to customise the functionality and presentation of mkdocs, we can build a documentation system that meets our needs. Here is a first basic configuration:

```yaml
site_name: ACME API Initiative Documentation

plugins:
  - search
  - multirepo:
      cleanup: true
      keep_docs_dir: true
      repos:
        - section: Decision Records
          import_url: 'https://github.com/danielkocot/decision_records_example?branch=main&docs_dir=*'

theme:
  name: material
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-schema: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
```

In this configuration, I use an integrated plugin for the search function and the <a href="https://github.com/jdoiro3/mkdocs-multirepo-plugin" target="_blank">mkdocs-multirepo-plugin</a> in addition to <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank">mkdocs-material</a>. The last plugin makes it possible to integrate external documentation repositories into the documentation system. Specifically, this is now the Decision Records from last week. With mkdocs-material, a few little helpers, such as Python Markdown Extensions, are added in addition to the actual theme. One special feature should be noted: mkdocs-material is available as an open source variant and as an Insiders fork, which is available for a monthly sponsorship. This is a good thing, as it keeps the project alive in the long term and, via Funding Goals, all users get access to all functions over time. But back to our initiative documentation. For the first time, we will now create it using `mkdocs serve`.

```yaml
❯ mkdocs serve
INFO     -  Building documentation...
INFO     -  Multirepo plugin importing docs...
✅ decision-records (1.162 secs)
INFO     -  Cleaning site directory
INFO     -  Multirepo plugin is cleaning up temp_dir/
INFO     -  Documentation built in 1.33 seconds
INFO     -  [01:05:39] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [01:05:39] Serving on http://127.0.0.1:8000/
INFO     -  [01:05:39] Browser connected: http://localhost:8000/
```

If we now go to `http://localhost:8000` in the browser, we get the following view.
![CleanShot 2023-05-09 at 09.18.32@2x.png](https://media.graphassets.com/zRQCGnxTFOUVZhj1QoPW)

So the documentation works already locally, but will reach so few to no one 😉 . Therefore, we need a central place where the documentation can be accessed. Since the decision records can be found on Github anyway, this is also a good place for the documentation. So we now create an action based on mkdocs-deploy-gh-pages. Before we look at the action further, we have to create a `requirements.txt` for the mkdocs plugins, because we need exactly the dependencies for the respective runs of the action.

```yaml
❯ pip freeze > requirements.txt
```

```yaml
name: Publish docs via GitHub Pages
on:
  push:
    branches:
      - main

jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main
        uses: actions/checkout@v2

      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AccessToken: $(System.AccessToken)
          CONFIG_FILE: mkdocs.yml
          EXTRA_PACKAGES: build-base
          # GITHUB_DOMAIN: github.myenterprise.com
          REQUIREMENTS: requirements.txt
```

With each push, the Github Action is executed and creates a new version of the documentation.
![CleanShot 2023-05-09 at 13.32.06@2x.png](https://media.graphassets.com/7vWDUPkKSlus9SbOwr2A)

## Conclusion
As we have seen, the development of a documentation system, which can also grow into a documentation platform, is possible with little programming effort, almost low-code-like. mkdocs with all its plug-ins and perhaps one or two of our own developments will accompany us on our way in the coming weeks. Next week we'll be looking in the direction of the API guidelines. So long!

## References

<a href="https://github.com/danielkocot/decision_records_example" target="_blank">GitHub - danielkocot/decision_records_example</a>

<a href="https://github.com/danielkocot/acme-api-initiative" target="_blank">GitHub - danielkocot/acme-api-initiative: An example for a documentation platform with mkdocs</a>

Photo by <a href="https://unsplash.com/@qwitka?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Maksym Kaharlytskyi</a> on <a href="https://unsplash.com/photos/Q9y3LRuuxmg?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>
  

Charge your APIs Volume 1 - Build a documentation system with mkdocs

Weitere Infos

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.

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.

Absenden

API Sprawl in der Ära des Great Unbundling: Herausforderungen und Strategien

API Sprawl in der Ära des Great Unbundling: Herausforderungen und Strategien

Weitere Infos

API Sprawl in der Ära des Great Unbundling: Herausforderungen und Strategien

Gemeinsam bessere Projekte umsetzen.

Wir helfen deinem Unternehmen.

Unsere Leistungen

Hilf uns, noch besser zu werden.

Zu den Jobangeboten