Canonical Microservice

Implementations of the same basic, canonical microservice using different programming languages and different frameworks:

• Exposes a simple REST API over HTTPS requiring authentication

• The exposed REST API is defined by an API specification, ideally using OpenAPIv3

• Persists entities in an external database, using MongoDB, but staying DB-independent as much as possible

• Invokes a publicly accessibe REST API that requires authentication

• All external calls (REST API invocations, DB access) use client-side resilience approaches: timeout, retry, fallback

• Publishes entity change events to a topic, using Kafka, but staying broker-independent as much as possible

• Subscribes to events from a topic, using the same broker as it uses for publishing events

• The event exchanges are described by an AsyncAPIv2 definition

• Loosely follows Hexagonal Architecture and thereby confines framework and technology dependence (Kafka, MongoDB, …​) to "adapters"

• Configuration via properties, using encryption for sensitive property values

• Packaged into an as-small-as-possible Docker container

Generic development steps

1. Write REST API spec

2. Write AsyncAPI spec

3. Create project with latest versions of all dependencies

4. Add unit testing support

5. Add property configuration support

6. Implement technology-independent "domain" incl. "ports":

   1. model

   2. domain services

   3. application service

   4. received event handlers

   5. "driven ports" (interfaces) for

      1. repository

      2. invoked REST API

      3. sending events

7. Implement technology-dependent "adapters":

   1. "driving adapters" for

      1. exposed REST API

      2. Kafka event subscription

   2. "driven adapters" for

      1. MongoDB repository

      2. REST API invocations

      3. Kafka event publication

8. Write Dockerfile