Ich habe einen ADR geschrieben, bin ich jetzt ein Architekt?

| de | en |

---

tl;dr Architecture Decision Records koennen helfen Architekur- und Implementierungsentscheidungen kurz, praegnant und entwicklerfreundlich zu dokumentieren.

Ich habe einen ADR geschrieben, bin ich jetzt ein Architekt?

Vor ein paar Wochen habe ich in einem Projekt eine Anforderung umgesetzt, mit der ein bestehender Microservice erweitert wurde. Es ging darum weitergehende Konfigurationsmoeglichkeiten auf Basis der bestehenden Daten zu schaffen und ueber die Benutzeroberflaeche zur Verfuegung zu stellen.

Schlussendlich war das Ziel Daten in eine Verknuepfungstabelle zu schreiben, bzw. daraus zu loeschen, um die Konfiguration zu aktvieren bzw. zu deaktivieren.

Bestehende Architektur

Der Microservice, der in .Net Core geschrieben ist, verwendet fuer die Kommunikation eine RESTful API.

Der betroffene Controller wird mit der Basis-URL <host>/api/pfad/controller/aktion/ angesprochen.

What’s new

Das Hinzufuegen der Konfiguration per HTTP-POST Operation (<host>/api/pfad/controller/aktion/{id}/zuordnungHinzufuegen) entspricht dem REST Standard. Beim Entfernen werden jedoch im Moment mehr Daten benoetigt, weshalb es nicht mit HTTP-DELETE implementiert werden kann, da DELETE keine weiteren Parameter akzeptiert.

Um moeglichst nah am bestehenden URL Schema zu bleiben habe ich die Aktion dann auch als POST implementiert ((<host>/api/pfad/controller/aktion/{id}/zuordnungEntfernen)).

Das Problem

Das Problem dabei ist natuerlich, dass jemand der auf den Code schaut, einen Widerspruch zwischen dem verwendeten POST Verb und dem Pfad- und Methodennamen ZuordnungEntfernen sieht und sich fragt, was der Schwachsinn soll.

ADR als Rettung

Dieser “jemand”, der sich dann ueber den Code und die Bezeichnung wundert bin in ein paar Wochen oder Monaten wahrscheinlich ich. Und wenn ich es nicht bin koennte die Person auf die Idee kommen mich zu fragen was ich mir dabei gedacht habe.

Fuer diesen Fall habe ich zum ersten Mal einen Architecture Decicision Record geschrieben und mit in der Anforderung im DevOps Server hinterlegt.

In Design It schreibt Michael Keeling ueber ADRs:

Capture architecture design decisions as they are made using a lightweight, text-based template. […] Retaining a history of decisions provides context for the current architecture relative to its evolution.[…]

Die Markdown Datei habe ich dann, wie oben beschrieben, zusammen mit dem Code abgelegt.

ADR als Markdown

# ADR_33333_01: Verwenden von POST als HTTP Verb fuer das Loeschen einer Zuordnung

## Status

Implementiert (Changeset #22222)

## Kontext

Das Gateway (GW) wird um die Moeglichkeit erweitert, dass jede Abteilung die
fuer sie passenden Ansprechpartner selber aktivieren kann.

Hierfuer muss dass GW zwei neue Methoden fuer die Aktivierung und die Deaktivierung
erhalten.
Waehrend die Aktivierung tatsaechlich eine neue Zeile in die DB einfuegt und somit
dem `POST`-Verb entspricht, loescht die Deaktivierung eine Zeile und sollte eigentlich
ein `DELETE` sein.

## Entscheidung

Die Deaktivierung wird trotzdem als `POST`-Operation implementiert.
Das ruehrt daher, dass ich fuer's erste bei einem Controller verbleiben will und
die ID in der ASP-Route schon fuer die Austauschpartner ID verwendet wird.
Die Abteilungsdaten muessen trotzdem uebergeben werden, was nicht in der URL geschehen soll.

## Konsequenzen

Die Handhabung fuer das Senden einer Deaktivierung entspricht derjenigen fuer die
Aktivierung und macht den Code besser verstaendlich.

Dieser Teil der REST-API wird im Moment nur im Projekt angesprochen und somit nur
intern genutzt, was eine korrekte semantische Verwendung der HTTP-Verben weniger
kritisch macht.

Sollte das GW in Zukunft erweitert werden und die entsprechenden Methoden in andere
Controller umziehen, bzw. der `AustauschpartnerPflegeController` und die Routen
umgebaut werden, sollte in Betracht gezogen werden, das semantisch Korrekte `DELETE`-Verb 
zu verwenden.

Bin ich jetzt ein Architekt?

Ich bin so viel und so wenig Architekt wie vorher auch. Vor allem laesst sich vortrefflich darueber streiten, ob die Entscheidung ueber das HTTP Verb tatsaechlich eine Architektur-entscheidung ist. Immerhin ist sie im Nachhinein, ohne tiefe Eingriffe in die Gesamtstruktur des Projekts aenderbar.

Allerdings habe ich an diesem Punkt auch nur nach einer sinnvollen Vorlage fuer ein Prosa-Dokument gesucht, die ich in einem technisch Kontext sinnvoll befuellen konnte und die in der Zukunft einer anderen Entwicklerin oder einem anderen Entwickler (oder mir selbst) einen etwas mysterioesen Sachverhalt kurz und knapp erklaert.

Das ADR Format hat mir hierbei geholfen.

Mehr Material

Formatvorschlag von Michael Nygard: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

Praesentation von Michael Keeling: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf