Building a REST Service in Java following Clean Architecture


The twelve-factor app methodology goes back to developers at Heroku - One of the
first cloud platforms that ever existed. The methodology consists of best
practices to build portable, resilient, and scalable web applications and was
presented by Adam Wiggins in 2011. Some argue that these twelve guidelines are
outdated and only apply to applications on Heroku. Honestly, eleven years in the
software industry are a lifetime. But, we do not share this opinion and claim
that this methodology is still relevant. The official website emphasizes that
the methodology is relevant for developers and operations engineers who develop
or manage apps or Software-as-a-Service (SaaS). In my opinion, it is also
relevant to software architects.

## Twelve-Factor App Methodology Overview

|      |                         |                                                                  |
| ---- | ----------------------- | ---------------------------------------------------------------- |
| I    | **Codebase**            | One codebase tracked in revision control, many deploys           |
| II   | **Dependencies**        | Explicitly declare and isolate dependencies                      |
| III  | **Config**              | Store config in the environment                                  |
| IV   | **Backing Services**    | Treat backing services as attached resources                     |
| V    | **Build, Release, Run** | Strictly separate build and run stages                           |
| VI   | **Processes**           | Execute the app as one or more stateless processes               |
| VII  | **Port Binding**        | Export services via port binding                                 |
| VIII | **Concurrency**         | Scale out via the process model                                  |
| IX   | **Disposability**       | Maximize robustness with fast startup and graceful shutdown      |
| X    | **Dev/Prod Parity**     | Keep development, staging, and production as similar as possible |
| XI   | **Logs**                | Treat logs as event streams                                      |
| XII  | **Admin Processes**     | Run admin/management tasks as one-off processes                  |

Source: https://12factor.net/. There is also a free e-book available on this topic
by Adam Wiggins: https://12factor.net/12factor.epub

## I. Codebase

Code is usually tracked in a version control system (VCS) whose state in
relation to a specific application is often referred to as a repository. The
relation between applications and code bases (aka source control) should be
one-to-one. This has multiple implications:

Each microservice is an app and should fulfil the twelve factors on its own.
Apps may not share code unless the shared code is a dependency. Each 
service/app should have its own CI/CD pipelines.

Further a single code base may have multiple deployments. Meaning, regardless of
the environment or system, your app always points to the same code base. Though,
it is possible there are different versions of the same app deployed across
environments. For example, you may deploy `v1.1.0` on your development
environment while your production environment still points to `v1.0.0`.

This greatly reduces the risk of desynchronization and eases collaboration.

## II. Dependencies

Applications should always explicitly define dependencies and never rely on them
implicitly. Also, dependencies should be isolated from the wrapping system to
prevent leakage. Version mismatches and missing dependencies are one of the most
annoying issues when setting up applications.

In the virtualization era, most people instinctively understand that explicit
dependency definition is crucial. Most languages have very mature package
managers that usually use a dependency declaration file. Dependencies do not
only relate to language-specific libraries but also to system tools. (Docker)
images for example fail to build if you rely on dependencies that are not
contained within your base image.

Tip: If you are using Python in your projects and still use plain pip, we would
like to encourage you to have a look at [Poetry](https://python-poetry.org/).

## III. Config

Configuration must be strictly separated from the code and stored centrally.
Information such as environment-related addresses, credentials, and settings
should be managed via a central configuration file. The configuration itself
should be managed by environment variables.

```python title='config.py'
DATABASE_DRIVER = os.environ.get('DATABASE_DRIVER')
DATABASE_NAME = os.environ.get('DATABASE_NAME')
DATABASE_HOST = os.environ.get('DATABASE_HOST')
DATABASE_PORT = int(os.environ.get('DATABASE_PORT'))
DATABASE_USERNAME = os.environ.get('DATABASE_USERNAME')
DATABASE_PASSWORD = os.environ.get('DATABASE_PASSWORD')
DATABASE_URI = f'{DATABASE_DRIVER}://{DATABASE_USERNAME}:DATABASE_PASSWORD}@{DATABASE_HOST}:{DATABASE_PORT}/{DATABASE_NAME}'
```

This has a major advantage, wherever your application is deployed,  all you have
to adjust is the configuration. Many platforms, frameworks, and solutions offer
external configuration management. For example, Kubernetes has configuration
maps, docker offers environment variables as `-e` flags and AWS EC2 may be fed
with environment variables by using the AWS CLI.

## IV. Backing Services

Backing services are dependencies of the application that are not code but
consumable operations. These may be databases, messaging- or queuing services,
SMTP servers, third-party APIs, or caches like Redis, to name a few. No matter
if the backing service is a local or remote dependency the application should
interact with it in the same way. These dependencies are resources to the
application and should be handled as such.

![Backing Services Example](/assets/blog/posts/twelve-factor/backing-services.svg)

This enables loose coupling by default and thereby grants almost unlimited
scalability and reliability of both apps and services and also highlights the
importance of configuration separation.

To define these backing services even more explicitly, invert their control,
maximize decoupling and ease testing greatly, we suggest you have a look into a
dependency injection framework in your corresponding language:

- Python dependency injector:https://github.com/ets-labs/python-dependency-injector
- InversifyJS: https://inversify.io/
- Java Spring IoC: https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/beans.html

## V. Build, Release, Run

DevOps is all around us. Not much to say for this point. It is recommended to
target fully automated and separated build and run stages. The more of your
processes are automated, the less can go wrong and the more time your save.

## VI. Processes

One of the major advantages of cloud applications is the ease of
scaling. But horizontal scaling doesn't come for free. You have to build your applications in
a way they are stateless.

Stateless in essence means, that there is no context information saved and each
request is an isolated operation. Concepts like JWT and external caches support us in
implementing apps and services in a stateless manner, without losing
functionality or computation speed.

Running an app as one or multiple stateless processes essentially enables
elasticity for the specific component.

## VII. Port Binding

This one aged badly. The initial proposal on this point was that the app should
be self-contained and be exposed by being bound to a port. Most of today's
applications are running on some kind of platform, service, or framework. By
default, many of these require port binding to access the component at all.

One important note though; This also implies that apps may be backing services
for other apps and thereby should be handled as such.

## VIII. Concurrency

There is a broad variety of concurrency approaches available. Not only across
languages, but also within. Most languages offer a way to scale either by
spawning multiple (child) processes or by creating threads. Applications should
be able to scale out via processes as workloads can become massive and
increasing the resources might not work well at a certain point.

In general, technologies that follow a uber-process approach with threads, tend
to be more resource intensive as technologies that utilize multiple processes.
An example for this is Java that is known for its massive resource consumption.
Though, this is often a negligible fact, as resources are cheap - Only at
massive scale would you notice an impact on your overall costs.

![Rough difference between multithreading and multiprocessing](/assets/blog/posts/twelve-factor/multithread-multiprocessing.svg)

## IX. Disposability

Disposability means that twelve-factor apps can be started and stopped at a
moments notice. This enables fast and elastic scaling as well as rapid
deployment of code and configuration changes. Apps should also shut down
gracefully to handle crashes and scale in scenarios. Containers and functions
almost always fulfil this requirement by default.

Serverless functions are a great example of how this concept may be used to
drastically reduce development effort and costs. Many cloud offerings include
serverless functions, such as AWS Lambda, Azure Functions, Cloud Functions on
Google Cloud Platform (GCP) or even Vercel Serverless Functions.

## X. Dev/Prod Parity

Environments should be as similar as possible. In fact, all that should be
different across your development, staging and production environments should be
configuration. This is a crucial concept to implement continuous delivery and
continuous deployments without encountering massive problems.

## XI. Logs

Logging is an often underrated task. Though, besides actual code, logging is the
most important task in distributed systems. Not implementing logging (correctly)
means you're flying blind. Nobody can maintain and debug such complex systems
without proper logging. Not being able to identify bugs in a production
environment can be frustrating, given the fact, you should never directly debug
a productive app, but only evaluate its logs.

These logs should be handled as streams and never be the concern of the app
itself. Instead, applications should write to `stdout` and then either be
handled by a terminal (locally) or a log-streaming/aggregation solution
(deployed). Meaning the logging aspect should be decoupled from the application
and be handled by the wrapping context.

To increase the readability and the capabilities to search and filter your logs,
you might want to have a look at a structured logging solution.

## XII. Admin Processes

There are often tasks that a developer or operator would like to see fulfilled.
These could be database migrations, synchronization jobs, or event-related
tasks. These should be executable as short-lived processes. An example of this
could be images that may be started with flags, cron-jobs, or serverless
functions.

## Summary

Even though this list isn't complete and some principles seem a bit outdate,
these twelve-factor principles are far from being irrelevant. Most of the points
are still highly applicable and should be understood and memorized by any
professional working in the software industry.

If you have additions or are not of our opinion, please let us know in the
comments to improve this wrap-up of the twelve-factor methodology.


The Twelve-Factor App Methodology


Hyrum Wright is a Staff Software Engineer at Google, according to his [LinkedIn profile](https://www.linkedin.com/in/hyrum-wright-0905427/). He made an observation nowadays
called "**Hyrum's Law**". It regards interfaces and API design and should be considered and memorized by anyone employed in the **software engineering** sector.

## Hyrum's Law

> With a sufficient number of users of an API, it does no matter what you promise in the contract: all observable behaviors of your system will be dependend on by somebody.
>
> Hyrum Wright on [https://www.hyrumslaw.com/](https://www.hyrumslaw.com/) - popularized by Google Employees and Titus Winters

## Definitions

To fully understand the impact of this sentence, we have to define a few things:

- **_API_** \- Any occurrence of an interface
- _**Interface** \-_ Not the concrete code pattern such as in Java, for example, but the abstract concept that defines the exposure of any consumable functions

## Significance and Meaning

Hyrum himself called this observation "**The Law of Implicit Dependencies**". But people at Google spread the name "Hyrum's **Law**" for the apparent reason of briefness. However,
that's also why nobody not knowing about it will understand what's meant.

A colloquial interpretation of this law could be: "Every change breaks someone's workflow", as ridiculously shown in a comic on [https://xkcd.com/1172/](https://xkcd.com/1172/).
But to understand that, we have to take a step back and look at the big picture: Anyone exposing his code as (re)usable functions inside a project, or for example, as a RESTful
APIs outside the project, usually does that for the sake of people to explicitly use the code. However, by the laws of statistics, all the observable behaviors your code supplies
will eventually be used by someone, thereby implicitly assuming things.

## Example

To [grasp](https://code-specialist.com/code-principles/grasp/) what these abstract sentences actually mean, take this example: You build an API that publicly delivers cat facts:

```json
{
  "catfacts": [
    "fact"
    :
    {
      "number": 1,
      "text": "Cats have 230 bones while humans only have 206."
    },
    "fact"
    :
    {
      "number": 2,
      "text": "Cats live longer if they live indoor."
    }
  ]
}
```

Given this information, people will implicitly assume that this interface serves cat facts in ascending order regarding their number. Meaning if the API delivers these facts in a
random order, it will break someone's system at some point if they, for example, always ship the first fact as the latest one. Or even less obvious: the API orders the items
concerning their first digit of the number.

```json
{
  "catfacts": [
    "fact"
    :
    {
      "number": 1,
      "text": "Cats have 230 bones while humans only have 206."
    },
    "fact"
    :
    {
      "number": 10,
      "text": "Abraham Lincoln had 4 cats that lived in the white house with him"
    },
    "fact"
    :
    {
      "number": 2,
      "text": "Cats live longer if they live indoor."
    },
    ...
  ]
}
```

This will also lead to a system or workflow breaking at some point. And it may be unfathomable to its maintainers why that is. The same applies to explicit changes, such as
introducing a new ORM on the backend side that leads to the items being delivered in the inverted order. Funny things can happen now if people try to fix this naively.

## Consequences of Hyrum's Law

The problem should be apparent by now. But what are the implications for software engineers, teams, and consumers?

The most straightforward answer could be: "Don't change anything". But that's ridiculous again. Anyone working in the computer science industry will confirm that "nothing is as
constant as change", and change is, in fact, a good thing, as it's the foundation of any improvement and innovation.

The uncomfortable answer is: we have to take this into account and mind as a software engineer and a consumer of these APIs.

- As the developer, we should **provide as much information explicitly** as possible, most likely in the documentation. This will reduce the number of people that make implicit
  assumptions about the API
- As the consumer, we should **assume as little as possible about APIs** we consume. Of course, there will still be assumptions made, but if you keep in mind that they are
  assumptions, you may save hours debugging your code.
- As a software architect, we should **plan APIs thoroughly to minimize behavioural changes**. New behaviour should belong to new endpoints.

## TLDR;

- **Hyrum's law** basically means: Whatever you deliver, someone is going to use it in a way you never imagined
- Change is necessary and will eventually break someone's system
- Give more explicit information on your interface to reduce the number of implicit assumptions
- Make fewer assumptions about code and, if applicable, test its behavior


Posts for the architecture Category

Building a REST Service in Java following Clean Architecture

The Twelve-Factor App Methodology

Hyrum's Law of Implicit Dependencies