I wrote an ADR, am I an architect now?
tl;dr
Architecture Decision Records can help to document architecture and implementation decisions in a concise, concise and developer-friendly way.
I wrote an ADR, am I an architect now?
A few weeks ago I implemented a requirement in a project to extend an existing microservice. The goal was to create advanced configuration options based on the existing data and to make them available via the user interface.
Finally, the goal was to write data into a link table or to delete data from it in order to activate or deactivate the configuration.
Existing architecture
The microservice, which is written in .Net Core, uses a classic RESTful API for communication.
The affected ExchangePartnerMaintenanceController is addressed with the base URL <host>/api/path/maintenance/exchangepartner/.
What’s new
Adding the configuration via HTTP-POST operation <host>/api/path/maintenance/exchangepartner/{id}/addReleation corresponds to the REST standard.
However, removing it currently requires more data, which is why it cannot be implemented with HTTP-DELETE, as DELETE does not accept any additional parameters.
To stay as close as possible to the existing URL scheme I implemented the action as POST <host>/api/path/maintenance/exchangepartner/{id}/removeRelation.
The problem
The problem, of course, is that someone looking at the code will see a contradiction between the POST verb used and the path and method name RemoveRelation, and wonder what the fuss is about.
ADR to the rescue
That “someone” who then wonders about the code and the name is probably me in a few weeks or months. And if it’s not me, the person might get the idea to ask me what I was thinking.
For this case, for the first time, I wrote an Architecture Decision Record and included it in the requirement in the DevOps server.
In Design It Michael Keeling writes about 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.
I then added the Markdown file together with the code, as described above.
ADR as Markdown
# ADR_33333_01: Using POST as HTTP verb for deleting a relation
## Status
Implemented (Changeset #22222)
## Context
The External Gateway (GW) will be extended with the possibility that each department can
activate contacts that are appropriate for them.
For this, the GW must implement two new methods for activation and deactivation.
While the activation actually inserts a new row in the DB and thus corresponds to
the `POST` verb, the deactivation deletes a row and should actually be a `DELETE`.
## Decision
The deactivation will still be implemented as a `POST` operation.
This is because I want to stay with one controller for the time being, and
the ID in the ASP route is already used for the exchange partner ID.
The department data must still be passed, which should not happen in the URL.
## Consequences
The handling for sending a deactivation is the same as for the activation and makes the code more understandable.
This part of the REST-API is currently only used by the project and is therefore only used internally,
which makes a correct semantic use of the HTTP verbs less critical.
Should the GW be extended in the future and the corresponding methods be moved to other
controllers, or the 'ExchangePartnerMaintenanceController', the routes
should be considered to use the semantically correct `DELETE` verb.
Am I an architect now?
I am as much and as little an architect as before. Above all, it is perfectly debatable whether the decision about the HTTP verb is really an architectural decision. After all, it can be changed in retrospect, without deep intervention in the overall structure of the project.
However, at this point I was just looking for a sensible template for a prose document that I could fill in a meaningful way in a technical context and that would explain a somewhat mysterious issue succinctly to another developer or to myself in the future.
The ADR format helped me with this.
More material
Suggested format by Michael Nygard: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
Presentation by Michael Keeling: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf