Raphael De Lio AsyncAPI & Springwolf

A little bit of context

The three tier application Present a tion L a yer Applic a tion L a yer D a t a L a yer

The thing is that… • When we a re a sked to m a ke a ch a nge in our system, it will likely be a ch a nge rel a ted to business • Since this is a n a rchitecture th a t h a s high cohesion of rel a ted technology (inste a d of high cohesion of business function a lity) • Usu a lly, these ch a nges h a ve to be m a de in a ll l a yers of our system Present a tion L a yer Applic a tion L a yer D a t a L a yer

Why do we organize our applications like that? • A pr a ctic a lly univers a l a rchitecture • Why is it univers a l? Present a tion L a yer Applic a tion L a yer D a t a L a yer

Why do we organize our applications like that? • M a ybe bec a use we a re likely to repe a t something th a t we h a ve seen before • Or m a ybe bec a use of how we tr a dition a lly org a nize people in comp a nies Present a tion L a yer Applic a tion L a yer D a t a L a yer Frontend Developers J a v a Developers DB Admins

Not a b a d a rchitecture. Just optimised over a set of forces th a t used to group people b a sed on f a mili a rity

These forces have changed • Aspir a tion a round softw a re development h a s ch a nged • We w a nt to ship softw a re much f a ster th a n ever before • We need to m a ke it e a sier to m a ke ch a nges in our codeb a se

Choosing cohesion of business functionality • In order to do it, we a lso need to ch a nge how we group code • This is forcing us to rethink the w a y our org a nis a tions a re structured • Which in turn is forcing us to group people by the w a y we bre a k our business a p a rt

Present a tion L a yer Applic a tion L a yer D a t a L a yer • So inste a d of org a nizing our codeb a se like th a t…

Business Line • We decided to st a rt org a nizing them like this… Business Line Business Line Business Line Business Line

Product C a t a log Te a m • And by org a nizing our code like this, we c a n now h a ve dedic a ted multidisciplin a ry te a ms working on e a ch slice of our a pplic a tion Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m

• And e a ch of these business lines h a s its own present a tion, business logic a nd d a t a l a yers fully m a n a ged by their respective te a m Present a tion Applic a tion Model Present a tion Applic a tion Model Present a tion Applic a tion Model Present a tion Applic a tion Model Present a tion Applic a tion Model

• It’s up to the te a m to decide their a rchitecture a nd technology used Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m I need a rel a tion a l d a t a b a se I work better with a document b a sed d a t a b a se

• Now, when we require a ch a nge in business to be m a de, it will likely f a ll under one dedic a ted te a m with full end to end responsibility of m a king ch a nges to this speci f ic business Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m I need a new noti f ic a tion to be sent when a n order is m a de

• There’s still a problem… our communic a tion is still coupled Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m Noti f ic a tion Te a m, send a noti f ic a tion for me! Ok a y! Will Do!

• It’s a lso ide a l to decouple the communic a tion between our services to a non blocking communic a tion Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m An order h a s been cre a ted! My cue!

• An event is a f a ctu a l st a tement a bout something th a t h a s h a ppened • Other micro-services c a n listen to the events they a re interested in a nd re a ct a ccordingly • The micro-services th a t listen to the event do not need to be re a ch a ble a t the time the event is emitted. And… • The microservice th a t is emitting the event doesn’t need to know a nything a bout the microservices th a t a re listening to the events… Decoupling the communic a tions between microservices • The distribution of responsibility we see in our event driven inter a ctions c a n mirror the distribution of responsibility we see in our org a nis a tions trying to cre a te more a utonomous te a ms Event Driven Communication

• Our softw a re a rchitecture is usu a lly driven by the w a y we org a nize our te a ms • We need to rele a se f a ster th a n ever before. This forced us to reorg a nize our te a ms a nd our softw a re a rchitecture • This force moved us to more decoupled te a ms, a rchitecture, a nd communic a tion. We moved tow a rds micro-services with communic a tions driven by events Quick Recap

• Even though the go a l is th a t we c a n ch a nge our softw a re freely, p a rts of our service will still be coupled to other services • If we bre a k comp a tibility with the consumers of our events, we will force them to ch a nge a s well • We still need to be a ble to cle a rly communic a te with other te a ms the det a ils a nd ch a nges of our extern a l contr a cts • And th a t le a ds us to… However

Async API

The need for better communication led us to… • St a rted in 2016 a t Hitch by Fr a n Mendez • Inspired by OpenAPI • Noticed a wide community w a s su ff ering from the s a me problems • Now under the Linux Found a tion • It’s a communic a tion contr a ct between senders a nd receivers

How does it work?

No content

Root elements Info server a sync a pi components oper a tions ch a nnel

Info Info version title extern a lDocs t a gs license cont a ct termsOfService description

Servers server p a thn a me host security v a ri a bles summ a ry description protocolVersion protocol bindings extern a lDocs t a gs

Channels ch a nnel title a ddress t a gs bindings servers p a r a meters mess a ges description extern a lDocs

Operations oper a tions summ a ry title bindings t a gs security a ction ch a nnel description tr a its mess a ges

Components components servers schem a s p a r a meters serverV a ri a bles securitySchemes mess a ges oper a tions ch a nnels correl a tionIds replies replyAddress extern a lDocs t a gs oper a tionTr a its mess a geTr a its serverBindings ch a nnelBindings oper a tionBindings mess a geBindings

Schemas

Schemas

Messages

Reply/Request oper a tions summ a ry title bindings t a gs security a ction ch a nnel description tr a its mess a ges

AsyncAPI Studio

Springwolf

History • Cre a ted in 2018 by St a v Sh a mir • Inspired by SpringFox • Downlo a ded more th a n a h a lf million times • Comp a tible with Spring K a f k a a nd Spring Cloud Stre a m • Monthly rele a ses • Strong a nd open community St a v Sh a mir Timon Beck C a rlos T a s a d a S a m0r040

What does it do?

Automated Documentation Generation • Autom a tic a lly cre a tes comprehensive document a tion: An a lyzes your Spring Boot code to underst a nd your a synchronous APIs. • Sc a ns for relev a nt a nnot a tions: Looks for @K af k a Listener a nd @R a bbitListener to identify mess a ge inter a ctions. • Extr a cts key inform a tion: G a thers det a ils a bout mess a ge structure, ch a nnels, oper a tions, a nd more.

AsyncAPI Compliant • Adherence to AsyncAPI speci f ic a tion: Document a tion follows the AsyncAPI st a nd a rd for event-driven a rchitectures. • St a nd a rdized structure a nd form a t: F a mili a r to developers experienced with OpenAPI (Sw a gger) for REST APIs. • Improved underst a nding: F a cilit a tes e a sier comprehension a nd a doption of the a synchronous API by a wider a udience.

Interactive Web UI • Web-b a sed interf a ce: O ff ers a user-friendly w a y to view a nd inter a ct with the gener a ted AsyncAPI document a tion. • E a sy n a vig a tion: Allows you to explore di ff erent p a rts of the document a tion e ff ortlessly. • Explor a tion of ch a nnels, mess a ges, a nd oper a tions: Provides det a iled insights into the components of your a synchronous API. • Enh a nced underst a nding: F a cilit a tes a deeper comprehension of how your a synchronous API functions.

Message Publishing • Publish mess a ges from the web UI: Send mess a ges to your a synchronous API directly within the document a tion interf a ce. • Simpli f ied testing a nd debugging: Allows for convenient inter a ction with the API during development a nd troubleshooting. • Improved developer experience: O ff ers a stre a mlined work f low for testing mess a ge inter a ctions without writing a ddition a l code

Bene f its • Reduced M a nu a l E ff ort: You don't h a ve to write a nd m a int a in complex AsyncAPI document a tion m a nu a lly. Springwolf does it for you, s a ving you time a nd e ff ort. • Improved Coll a bor a tion: The st a nd a rdized a nd inter a ctive document a tion m a kes it e a sier for di ff erent te a ms (development, QA, etc.) to coll a bor a te on a synchronous API projects. • F a ster Onbo a rding: New developers c a n quickly get up to speed with your a synchronous API by exploring the gener a ted document a tion. • Enh a nced Testing: The mess a ge publishing fe a ture (if en a bled) simpli f ies testing a nd debugging of your a synchronous API.

How does it do it? • Gener a tes a n AsyncAPI f ile a utom a tic a lly by sc a nning a nnot a tions such a s @K af k a Listener, @SqsListener, a nd @R a bbitListener • Provides a UI a llowing us to quickly see which ch a nnels our a pplic a tions inter a ct with • Gener a tes ex a mple p a ylo a ds for our schem a s • Allows us to send mess a ges to our broker directly from the UI

Let’s look at the code

What’s next?

Try it out!

Contribute!

Raphael De Lio • Softw a re Consult a nt @ Xebi a • Knowledge sh a rer: - YouTube - Medium - Spring Builders • Kotlin Dutch User Group Org a nizer