This post proposes five principles for API design, summarized as POINT: purposeful, style-oriented, isolated, channel-neutral, and T-shaped.

Context: Web API Design and Evolution (WADE)

Application Programming Interfaces (APIs) have been around for a long time, both local ones inside modular programs and remote APIs connecting operating system processes and distributed systems. Message-based protocols such as RESTful HTTP, gRPC, and GraphQL dominate the remote API realm.

IMHO, any API, whether local or remote, should address an actual client information or integration need. When delivering related functionality, three types of quality attributes are particularly relevant:

  • Developmental qualities. APIs should be straightforward to learn and easily consumable for developers and…

Service-Oriented Analysis and Design with DDD and MDSL (Source: [1])

This post shows how to advance from a set of user stories to OpenAPI specifications to API provider stubs via strategic and tactic DDD. This seven-step journey is partially supported and automated in two open source tools, Context Mapper and Microservice Domain-Specific Language (MDSL) Tools. Background information is available here and here.

Prerequisites: The instructions below assume that you have Context Mapper Version 6 and MDSL Tools Version 5 installed.

Step 1: Elicit Functional Requirement(s)

Write a user story in the Context Mapper DSL (CML), as explained in the Context Mapper documentation:

UserStory PaperArchiving { As a "Researcher" I want to create a "PaperItem" with…

My Frequently Accessed Venues (FAVs)

This post points you at valuable templates for documenting software architectures as well as a pattern languages that can support their creation.

Architecture Description Formats

When it comes to documenting software architecture requirements and designs, some of my most frequently visited resources are:

  1. The twelve-section arc42 template “takes the pain out of documentation” and is accompanied by many hints.
  2. ISO/IEC/IEE 42010:2011, defining what frameworks are and making the case for capturing decision rationale. There is a template to ease the creation of 42010-compliant architecture descriptions[1].
  3. OpenUP seems to have lost weight in recent years[2]. But it still is a good place to look…

The Software Engineering Alphabet

Aspect-Oriented Programming (AOP), Behavior-Driven Development (BDD), CDD, DDD, EDA… can we cook some more “method and practice soup”?

Background and Context

Story 22 on “Diagram-Driven Design” in Gregor Hohpe’s (highly recommend) “Software Architect Elevator” reminded me that I was one of the pundits that once contributed to an “A-Z list of 26 new development strategies” .

This post is a little more conservative and reminds us of actually existing ones.

Are your Designs “Driven”?

Some “driven” methods and styles (past and present) are:¹

A Collection of “Mighty” Method Elements on GitHub

Real-World Architecture Metaphor: Repositories, Artifacts/Building Blocks, Patterns, Architectural Style(s)

The Design Practice Repository (DPR) on GitHub compiles proven method elements and other knowledge nuggets for API and (micro-)service design — and more general software architecture work.

Update (December 8, 2020): Story splitting and CRC cards now featured, tutorial enhanced with architecture decision record(s), many elements edited and additional background information provided.

Methods: The Good, The Bad and The Why

Read on if you agree:

We all learn well from mistakes — but do these mistakes have to be our own?

You might be thinking that methods (and patterns) are on the other side of cool in the age of Agile, search engines and online developer communities. Who…

Business value/risk, stakeholder concern, quality level, external dependencies, cross-cutting, first-of-a-kind, past troublemaker?

What is important when analyzing and designing software architectures, and what is not? This post proposes 5+2 criteria for the architectural significance of requirements (and other artifacts) and applies them to several examples.


Let’s assume it is the first day for you on a project that has been running for a while (for instance, one that modernizes some legacy system); you might be an external consultant that has just been hired, or have switched role and project internally. What to work on first?

As a software engineer with architecture responsibilities, I would like to prioritize technical issues quickly so…

Three positions and evidence for one of them

Microservice architectures evolved from previous incarnations of Service-Oriented Architectures (SOAs) to promote agility and elasticity. They are often visualized with hexagons and onions (to emphasize service autonomy):

I see such microservices (defined by seven tenets here) as a contemporary implementation approach for Service-Oriented Architecture (SOA) principles and patterns, emphasizing and benefiting from modern software engineering practices such as domain-driven design, containerization and DevOps.

Please read on if you would like to learn why — or disagree.

Revolution! Stagnation! Evolution!

Three rather different positions can be observed, both online and in print:

  1. Microservices as a new architectural style competing with SOA and to be…

A consolidated definition for an overloaded term

Photo by Enrique Ortega Miranda on Unsplash

This post defines microservices via seven tenets, reverse-engineered from books, articles and blogs. It also recapitulates which Service-Oriented Architecture (SOA) principles and patterns I collected to introduce SOA between 2003 and 2009. Such consolidated definitions are required to analyze the SOA style and microservice-based SOA realizations objectively.

What Is in a Microservice?

My paper “Microservices Tenets: Agile Approach to Service Development and deployment” , published in a scientific journal but also openly available, compares several early definitions and distills seven tenets from them:

Evidence, criteria, agreement, documentation, realization/review

It is good to know when the most responsible moment for an architectural decision about a pattern or technology has come. But when can a decision be considered done? This post suggests five criteria to help you decide whether you are ready to move on.

Photo by Massimo Sartirana on Unsplash

The proposal is inspired by the five SMART criteria used in project and people management (but also when eliciting non-functional quality requirements). Let’s look at them one at a time.


You have gained reason to believe that the chosen design (selected pattern, technology, product or open source asset and its configuration, that is) will work…

A light template for architectural decision capturing

Architectural Decisions (ADs) answer “why?” questions about design and justify why an option is chosen. As a consulting IT architect at IBM, I followed their ARC-100 template for AD capturing on my projects, usually trimmed down quite a bit (following the first law of method adoption: “if in doubt, leave it out”). As a researcher, I proposed an even richer meta model later, optimized for decision reuse (decisions required, not decisions made, that is, or AD issues as opposed to outcomes). …

Doc SoC

Domain-Driven Designer, Architectural Decision Maker, Serviceorienteer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store