Der Vortrag behandelt die Methode 'API First' zur Entwicklung von Microservices unter Verwendung von OpenAPI, Vert.x und Kotlin, um die Effizienz in Softwareprojekten zu steigern. Dabei wird diskutiert, wie eine konsistente API-Definition vor der Implementierung erstellt und die Dokumentation verbessert werden kann, um Wissen innerhalb von Entwicklerteams besser zu transferieren. Das Konzept bietet Vorteile in der Code-Klarheit und der Vereinfachung des Entwicklungsprozesses, insbesondere in agilen Umgebungen.

1. Eine Stunde was mit API FirstEine Stunde was mit API First
Microservices bauen mit OpenAPI, Vert.x und Kotlin
Jan Weinschenker • Holisticon AG
@janweinschenker
1

2. AgendaAgenda
1. Wie entstand dieser Talk?
2. Wir wollen produktiv arbeiten™
3. API First! — Warum ist das eine gute Idee?
4. Wir unterstützen das™ vert.x und Kotlin
5. Fazit
2

3. Holisticon AG — About usHolisticon AG — About us
• @holisticon
Die Holisticon AG ist eine Management- und IT-Beratung mit
Niederlassungen in Hannover und Hamburg. Wir entwickeln beste
Individualsoftware, Webplattformen und Apps. Geschäftsprozesse
durchdringen wir und automatisieren sie. Große Datenmengen machen
wir mit Smart-Data-Ansätzen beherrschbar.
... und das alles agil.
www.holisticon.de
3 . 1

4. Holisticon AG — About usHolisticon AG — About us
3 . 2

5. 1. Wie entstand dieser Talk?1. Wie entstand dieser Talk?
Ein Projekt mit > 70 Menschen
Viele Teams
Microservice-Architektur
Java, Scala, Kotlin, JavaScript, Typescript, ...
4 . 1

6. 1. Wie entstand dieser Talk?1. Wie entstand dieser Talk?
Vergleichsweise wenige Entwickler bauen Software für viele andereVergleichsweise wenige Entwickler bauen Software für viele andere
Entwickler.Entwickler.
Häufig disruptive Änderungen an Code und Schnittstellen
(APIs).
4 . 2

7. 1. Wie entstand dieser Talk?1. Wie entstand dieser Talk?
Andere Entwicklerteams treten als Kunden (i.S.v. Scrum)
auf
Wenig Zeit für Support und das Schreiben von Doku
Großer und steigender Bedarf an guter Dokumentation
und Entwickler-Support
4 . 3

8. 1. Wie entstand dieser Talk?1. Wie entstand dieser Talk?
Über Sinn und Unsinn geschriebener Doku ...
4 . 4

9. Sigberg’s First Law of DocumentationSigberg’s First Law of Documentation
In order for someone to read a document they must first:In order for someone to read a document they must first:
Know that it exists
Know where to find it
Care enough about the subject to actually take the time
out of their life to look it up
https://medium.com/@thorbjorn.sigberg/sigbergs-laws-of-documentation-fab155b2415b
4 . 5

10. Arnold's Laws of DocumentationArnold's Laws of Documentation
1. If it should exist, it doesn’t
2. If it does exist, it’s out of date
3. Only documentation for useless programs transcends
the first two laws
aus: Murphy's Law von Arthur Bloch
4 . 6

11. aus:aus: Extreme ProgrammingExtreme Programming
Josh Susser, devchat.tv Podcast
Kent Beck
“a comment is a lie waiting to happen”
“A comment is the code’s way of asking to be more clear”.
4 . 7

12. 1. Wie entstand dieser Talk?1. Wie entstand dieser Talk?
Durch die Erkenntnis, dass es sehr schwierig und gleichzeitig
sehr notwendig ist, gute Doku zu haben.
Wissenstransfer zwischen Entwicklern ist essentiell.
4 . 8

13. 1. Wie entstand dieser Talk?1. Wie entstand dieser Talk?
ZusammenfassungZusammenfassung
Doku und Implementierung entwickeln sich auseinander
Wie kann man diese Divergenz vermeiden?
4 . 9

14. 2. Wir wollen produktiv arbeiten™.2. Wir wollen produktiv arbeiten™.
Dafür sind wir auf das Wissen anderer Entwickler*innen
angewiesen.
Funktionierender Code ist das beste Medium für diesen
Wissenstransfer.
5 . 1

15. 2. Wir wollen produktiv arbeiten™.2. Wir wollen produktiv arbeiten™.
WunschzustandWunschzustand
APIs müssen ohne große Hürden anfassbar sein
Anstatt sich in Doku einzulesen, APIs einfach
ausprobieren
z.B. API-Spielwiese im Webbrowser
□ mehr dazu später ...
5 . 2

16. 2. Kein Appell gegen geschriebene Doku!2. Kein Appell gegen geschriebene Doku!
Für dasFür das Big PictureBig Picture::
Geschriebene Doku, Schaubilder und Diagramme
Entwicklerdoku:Entwicklerdoku:
Funktionierender, intuitiver Code
Tools und UI, die einfach anzuwenden sind
5 . 3

17. 3. API First!3. API First!
Alles steht und fällt mit der Güte der Schnittstelle!
API muss konsistent und intuitv sein
Nachträgliche Änderungen an API sind teuer
6 . 1

18. 3. API First!3. API First!
Ergo:Ergo:
API als First-Class-Citizen im Entwicklungsprozess
Schnittstellenbeschreibung (API Spec)
Entwurf vor der Implementierung :
□ Ressourcen, Operationen, Datenobjekte, Statuscodes
6 . 2

19. 3. API First!3. API First!
Frühere Ansätze für API Specs:Frühere Ansätze für API Specs:
CORBA IDL (1991 bis 2011*)
WSDL (2000 bis 2007*)
Apache Thrift (2011 bis 2017*)
*Letztes Release
7 . 1

20. 3. API First!3. API First!
Alternativen im REST-ZeitalterAlternativen im REST-Zeitalter
RAML — RESTful API Modeling Language
API Blueprint (Markdown)
Swagger / OpenAPI
7 . 2

21. 3. API First!3. API First!
Alternativen im REST-ZeitalterAlternativen im REST-Zeitalter
RAML — RESTful API Modeling Language
API Blueprint (Markdown)
Swagger / OpenAPI
7 . 2

22. 3. Swagger / OpenAPI3. Swagger / OpenAPI
Entscheidung für OpenAPI, weil:Entscheidung für OpenAPI, weil:
Sehr gutes Tooling
Unterstützung für alle gängigen Sprachen
Einbindung in bestehende CI/CD-Prozesse leicht möglich
7 . 3

23. 3. Swagger / OpenAPI3. Swagger / OpenAPI
API Spec basierend auf YAML
Hieß Swagger seit 2011
2016 umbenannt in OpenAPI
Umfangreiches Tooling
□ Gradle, Maven, Swagger UI, etc
□ Generatoren für Testdaten
7 . 4

24. 3. Swagger / OpenAPI3. Swagger / OpenAPI
Generator für Client- und Server-Code, SDKs, ...
Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy,
Vertx, Google API Client Library for Java, Rest-assured, Spring 5 Web Client)
Scala, Kotlin, Dart, Ada, JavaScript, Typescript-Angular,
Clojure, C#, C++, Swift, Ruby, Python, Rust, Haskell, Elm, ...
Swagger UI
7 . 5

25. 3. Swagger / OpenAPI3. Swagger / OpenAPI
API Spec für das REST-Zeitalter
paths:
/apod: # https://www.my-cool-service/apod
post:
summary: create an apod with the specified date
requestBody:
required: true
description: The rating you want to set
content:
application/json:
schema:
$ref: '#/components/schemas/ApodRequest'
responses:
'201':
description: Apod entry created
headers:
location:
schema:
type: string
description: The location of the created resource.
7 . 6

26. 3. Swagger / OpenAPI3. Swagger / OpenAPI
API Spec für das REST-Zeitalter
paths:
/apod: # https://www.my-cool-service/apod
get:
summary: get all apods
responses:
'200':
description: An array of apods or an empty array, if no data is availab
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Apod'
'500':
description: Server side error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
7 . 7

27. 3. Swagger / OpenAPI3. Swagger / OpenAPI
API Spec für das REST-Zeitalter
components:
schemas:
Apod:
description: the apod data object
required:
- id
properties:
id:
readOnly: true
type: string
dateString:
readOnly: true
type: string
title:
readOnly: true
type: string
imageUriHd:
readOnly: true
type: string
nullable: true
7 . 8

28. 3. Wir wollen produktiv arbeiten™3. Wir wollen produktiv arbeiten™
API Spec, kann ...API Spec, kann ...
den Medienbruch beim Implementieren vermeiden
über Repositories im Projekt verteilt und versioniert
werden
Kann uns und anderen Entwicklern das Leben erleichtern
7 . 9

29. 4. Wir unterstützen das™:4. Wir unterstützen das™: KotlinKotlin..
Schlauer Compiler
Statische Typisierung
Wenig Boilerplate
Excellente IDE Unterstützung, zumindest wenn der
Hersteller Jetbrains heißt
8 . 1

30. 4. Wir unterstützen das™:4. Wir unterstützen das™: KotlinKotlin..
OpenAPI generiert u.a. Kotlin Data classes
8 . 2

31. 4. Wir unterstützen das ™:4. Wir unterstützen das ™: Vert.xVert.x
Reactive Streams: Observable, Single, Maybe,
Completable, ...
Multi-Reactor-Pattern, ähnlich Node.js.
Unabhängige Komponenten (Verticles) kommunizieren
über einen Eventbus.
Single Threaded, Non-Blocking
8 . 3

32. 4. Wir unterstützen das ™:4. Wir unterstützen das ™: Vert.xVert.x``
8 . 4

33. 4. Wir unterstützen das ™:4. Wir unterstützen das ™: Vert.xVert.x
Vert.x verwendet die API-Spec für das Request-Routing und
die Request-Validierung.
OpenAPI3RouterFactory
.rxCreate(vertx, "swagger.yaml")
.map { routerFactory -> routerFactory.mountServicesFromExtensions() }
.flatMap { httpServer -> httpServer.rxListen(port) }
.subscribe()
8 . 5

34. 4. Unser Beispiel: Astronomy Picture of the Day4. Unser Beispiel: Astronomy Picture of the Day
https://apod.nasa.gov
https://api.nasa.gov
8 . 6

35. 4. Wir unterstützen das ™:4. Wir unterstützen das ™: Vert.xVert.x
/apod/{apodId}:
x-vertx-event-bus:
address: apod_query_service.apod # >>> Mapping auf implementierende Klasse
get:
summary: get an apod for the specified date
operationId: getApodForDate # >>> ID dieser Operations
x-vertx-event-bus:
method: getApodForDate # >>> Mapping auf implementierende Method
parameters:
- name: apodId
in: path
required: true
description: the id of the picture
schema:
type: string
pattern: '^d+$'
8 . 7

36. DemoDemo
1. OpenAPI Spec
2. Swagger UI
3. Einen weiteren Endpunkt implementieren
8 . 8

37. FazitFazit
API First! kann den Projektalltag erheblich vereinfachen
Ideal für Microservices
Tooling ist wichtig
9

38. Vielen DankVielen Dank
CreditsCredits
Icons von Eucalp. https://www.flaticon.com/authors/eucalyp
10

39. MoreMore
LinksLinks
□
□
□
□
Sourcecode des Beispiels bei Github
https://github.com/holisticon/vertx-kotlin-example
Swagger.io
https://swagger.io
Swagger editor
https://editor.swagger.io
vert.x
https://vertx.io
11