Category Archives: Software Design

The Functional Core, Imperative Shell Pattern

The Functional Core, Imperative Shell pattern is just so exciting! 🔥

This pattern enables us to use functional programming for what it does the best, and to use imperative programming for all the messy, mutable, side-effectful stuff that most applications also need to do. And what makes this pattern super nice is that it provides a clear separation between the two programming styles, so they can peacefully coexist in the same application.

The Functional Core, Imperative Shell pattern is similar to Hexagonal Architecture, Ports and Adapters, Clean Architecture, and similar styles that, a bit simplified, are characterized by two key architectural attributes:

  1. There is a core with the core business logic, and a shell that handles interactions with the outside world, such as persisting data in databases or providing UIs to interact with end users.
  2. The shell can call the core, but the core cannot call the shell and the core is even unaware of the existence of the shell. This is also known as the Dependency Rule (see, for example, Clean Architecture to learn more about this rule).

An additional architectural attribute in the Functional Core, Imperative Shell pattern is, unsurprisingly, that the core should be written in a functional style, meaning using immutable values and pure functions.

The key objectives in the Functional Core, Imperative Shell pattern is to separate functional code and imperative code, and to minimize the imperative code, so when in doubt whether a piece of functionality belongs in the core or shell, then make it functional and put it in the core.

💡 Book Tip: If you want to use Domain-Driven Design and functional programming (for example, in the Functional Core, Imperative Shell pattern), I can warmly recommend Domain Modeling Made Functional, a truly awesome book 👍

In practice, the core will often be an instance variable in the shell. The shell will call the core with a value and get a new value returned, and then do side-effectful, imperative stuff, like displaying it to a user or storing it in a database, with value returned from the core.

If you’d like to read more about the Functional Core, Imperative Shell pattern, I recommend the links below:

Thank you for reading. Hope you will find this pattern useful. If you know someone who might enjoy this article, please share it 🙏

The Backends for Frontends (BFF) Pattern

Many textbooks assume that your frontend will just call a single, beautiful, and secure API, but in the real-world this is rarely the case…

For example, imagine a bank that offers both banking and insurance to its customers. The bank has acquired the insurance business, which already had an insurance solution. The customer master data is stored in a CRM system. So if we were tasked with developing a customer self-service portal for the bank, the portal would need to call three different systems (CRM/Bank/Insurance), with three different protocols, and three different security schemes, just to get a basic overview of a customer’s engagement with the bank.

A common way to overcome this imperfect setup is to create a new backend in front of the real backend(s) and then design the perfect API for the frontend.

This is known as the Backends for Frontends (BFF) pattern and an example (using our imaginary bank) is shown below:

The Web BFF in the diagram above can expose a simple GET /customers/{id} REST operation that our frontend can call instead of dealing with the complexity of calling and integrating three different systems.

Beside respecting the separation of concerns principle, by separating our presentation logic from our integration logic, we get many more benefits from using the BFF:

  • Call the backends in parallel: We can call the backends in parallel and perhaps respond faster to the end user.
  • Filter the responses: We can remove internal or sensitive data, such as an unwanted customer flag, or unnecessary data that just adds complexity to the frontend and drains battery power when parsing on mobile devices.
  • Transform the responses: We can transform the responses to the frontend into something more usable, such as translating internal codes to something more descriptive. For example, a code in a job field can be translated from SH_CLERK to Shipping Clerk.
  • Enhanced security: We can add extra security in the BFF, such as OAuth2, to protect the unsecure backend solutions, and we can implement a single sign on, so the frontend doesn’t need to deal with different authentication methods in different backend systems.
  • Handle different protocols: The BFF can call FTP, SOAP, REST, GraphQL, and other types of services, but still use a single protocol when interacting with the client.
  • Encapsulate advanced business logic: Issuing a new insurance policy may be a complex operation that requires multiple service calls, but this can be simplified for the clients into a single end point with only the absolute minimum data in a flat structure.
  • Caching across clients: Some of backends may be slow so caching across different clients may be an effective way to deliver acceptable response times to the end users. Moreover, if we need to call usage-based external APIs, it may also be worth caching those responses across clients to reduce the cost.
  • Protect the client from changes to the backend: Changes in the backends APIs need not to result in changes in the UI, the changes can be handled in the BFF.
  • It’s still just code: A BFF doesn’t involve canonical data models, ESBs, or other old-school integration patterns that are complex and time consuming to deal with; it’s just plain code. Moreover, a change in the BFF will not affect other systems, like with an ESB, so it is better aligned with DevOps and microservice thinking.

The main drawback of the BFF pattern is that, at least in the beginning, it can seem like extra work for the frontend team (which should be the ones developing and owning the BFF) but it usually pays back if the underlying backends are non-trivial. Remember that there are no technical restrictions to what language / framework we can use for the BFF; if the frontend team is skilled in JavaScript, they may be more comfortable with writing the BFF in Node.js and that’s perfectly fine.

The Circuit Breaker Pattern

When we start using external services in our code, we introduce a whole new range of potential problems, such as timeouts and service unavailability, that we don’t need to deal with when using in-memory API calls.

For example, a web shop can be designed to scale automatically to handle peak loads, such as Black Friday, but if its core business process depends on an external service that breaks under unexpected loads, then the whole web shop can be brought to its knees, unless we design for this situation.

One of the best ways to address this problem is to use the circuit breaker pattern, which stops all calls to an external service when that service is unavailable and then the circuit breaker returns an artificial response instead (more on that later).

In the Java-based NewsReader example in the previous blog post, we can add a circuit breaker as a decorator around the Feed interface as seen in the diagram below:

A pseudocode implementation of the FeedCircuitBreaker class is shown below:

public final class FeedCircuitBreaker implements Feed {
    private Feed feed;
    private List<Post> cache = Collections.emptyList();

    private boolean circuitOpen = true;
    private LocalDateTime circuitRetry;

    public FeedCircuitBreaker(Feed feed) {
        this.feed = Objects.requireNonNull(feed);

    public List<Post> getPosts() {
        // Is it time to reopen the circuit and try again?
        if(!circuitOpen && {
            circuitOpen = true;

        if(circuitOpen) {
            try {
                cache = feed.getPosts();
            } catch(Exception e) {
                // Close the circuit and wait 5 minutes before trying again
                circuitOpen = false;
                circuitRetry =;

        return cache;

And using the circuit breaker is a matter of decorating an underlying feed:

Feed f = new FeedCircuitBreaker(new TwitterFeed("@KennethLange"));

The tricky part of the circuit breaker pattern is to design the right fallback strategy where we need to decide what will happen when the external service is unavailable. There are many different fallback strategies we can choose from, and some of the most common ones are shown below:

  • Crash and burn: We assume errors will not occur and don’t design for it. For example, we have all seen websites where raw PHP errors are shown directly in the HTML returned to the end users (not recommended, neither from a usability nor security point of view).
  • Wait and see: Inform the users that the service is temporarily unavailable and encourage them to try again later. Wikipedia has an example of this implemented in PHP.
  • Alert an operator: A manual task is created for an operator. For example, to check whether the RSS feed has been moved to a new address.
  • Empty response: We return an empty response. For example, if the response from a service is used for displaying product recommendations on a website, then we can return an empty list and let the UI act as if there were no product recommendations.
  • Default response: We return a safe default response. For example, in an insurance claims process, we can default the fraud risk to high, to be on the safe side, but otherwise continue with the automated process.
  • Cached response: We return the last successful response. Like in the example with the newsreader earlier in this post.
  • Degraded response: We use local data to generate a lower quality response as a substitute for the real one. For example, in the insurance claims process in the previous bullet then if it’s a VIP customer who hasn’t reported a claim during the last year and the claim amount is less than $1,000 then we consider the fraud risk as being low.
  • Eventual consistency: We will synchronize the systems later. For example, if our web shop cannot access the inventory system, we will still take the customer’s order, put the request in a queue, and update the inventory system when it eventually becomes available again.

The right fallback strategy is almost always a business decision. For example, issuing motor insurance policies based on partial information may be an unacceptable risk and a wait and see strategy should be used. But for a web shop it may be a better fallback strategy to accept the customer’s order, without knowing if we are able to fulfill it, and then send a gift certification if we later realize that we cannot fulfill the order.

That’s it. I hope you enjoy this short post about a design pattern that doesn’t get all the attention that it deserves.

The Ports and Adapters Pattern

Most software solutions today are part of an active ecosystem where calling external services is an integrated part of its business processes. However, external integrations come with all kinds of headaches, from keeping your code clean, to executing automated tests within a reasonable timeframe, to the tight integration of external services into your code which makes switching vendors hard, if not impossible.

The ports and adapters pattern (also known as hexagonal architecture) is an effective way of addressing these problems. The problem for existing applications is that re-architecting them may not be economically feasible. So a minimalist approach is to use ports and adapters when you call external services, which you do not control, but not necessarily when using external libraries or products, which you do control.

The basic concept behind ports and adapters is very simple: You define a port that can be used with various adapters as long as the adapters conform to the port’s interface. An example from the physical world is the HDMI port in your laptop, which you can connect to any monitor as long as the monitor obeys the HDMI standard.

Moving back to software, then a simplified example of using ports and adapters is shown in the Java-based newsreader below:

The core package contains the core logic of the newsreader. I know that the feedreader will need to connect to various newsfeeds, but I don’t want to pollute my core code with all kind of implementation details, such as storing Twitter client secrets, obeying rate limiting in the API calls, dealing with broken XML in RSS feeds, so I define the Feed interface that defines the methods that I need a feed to offer.

The Feed interface can be something really simple like the code snippet below:

public interface Feed {
    List<Post> getPosts();

All the implementation details, I keep in the infrastructure package where I keep the implementations of different news feeds, such as RSS and Twitter. To avoid polluting the core code with implementation details, the key is to use inversion of control, so the core package has no dependencies on the infrastructure package.

When your application needs to connect the core code with the infrastructure code, you can use dependency injection in your application:

// Initialize the feeds from the infrastructure package
List<Feed> feeds = new ArrayList<>();
feeds.add(new RssFeed(""));
feeds.add(new TwitterFeed("@KennethLange"));

// Inject the feeds into the FeedReader
FeedReader reader = new FeedReader(feeds);
for(Post post : reader.getRecentPosts()) {

Beside the benefit of keeping the concerns of core and infrastructure code separate, you can add new feeds, such as Atom or Google News, without touching the core code. If Twitter shutdowns their APIs then you do not end up with dead Twitter code scattered throughout your application, and you can provide other feeds that provide similar content.

Another benefit is that your unit tests of the core code become much more reliable as you can easily make a fake (or stub) implementation of the Feed interface for testing purposes. This both means that you no longer need to rely on unreliable infrastructure in your tests and the unit tests will most likely become a lot faster to execute, which will also benefit your continuous integration.

Beyond Java
The basic idea of ports and adapters is that you define an interface and can collaborate with anyone who implements the interface. The concept is not limited to Java or other languages that offer an interface type. You can even define the interface as a service contract, perhaps in Swagger, and can then collaborate with any third-party service that implements the contract. This is similar to how webhooks work and would result in a very loose coupling where you would not even need to redeploy your code to support a new service. The difficulty would obviously be to get third parties to support your service contract.

When you call external services as part of your business processes, it is usually a good idea to stick in circuit breaker to avoid instability from a third-party service to spread to your system, so if the third-party service goes down, then your system doesn’t go down with it. The circuit breaker pattern will be the topic of my next blog post to improve improve the way we use external services in our code.

Don’t Limit Your REST API to CRUD Operations

I think one of the best things about RESTful web services is the Collection Pattern. It’s a really smart and developer-friendly way of designing a REST service.

For example, the Task REST API below, which is taken from my company’s REST API, is a typical example of how the collection pattern looks:

The collection pattern is so widely adopted that even a REST newbie, who has never seen this API before, will be able to guess the description in the Task column based on the content in the Method and Path columns.

The collection pattern is also really smart from a code perspective, because many frameworks have some sort of Active Record implementation on top of the collection pattern, so the framework can automatically wrap the whole REST service in a convenient way.

For example, in the old AngularJS framework they had this wonderful $resource factory that you could simply give the URI of a REST service that followed the collection pattern – and then the $resource factory would automatically figure out the rest (no pun intended!)

var Task = $resource('/tasks/:taskId', {taskId: '@id'}); 

var task = new Task(); 
task.description = "Put a man on the moon."; 
task.assignee = "James Webb"; 

While the collection pattern is really clever and so easy to use – and the best solution for almost all REST services – there are some edge cases where its CRUD approach just doesn’t make sense and other patterns should be considered.

Now it gets controversial…

When the web was the new big thing – and online pet shops were worth hundreds of millions of dollars – you would see web pages with HTML forms like this: 

<form method="POST" action="send_mail.cgi">
    <input type="text" name="subject">
    <input type="text" name="message">
    <input type="submit" value="Send Message">

While you can long for those innocent days when you could publish code like that on the web and not be flooded with spam; the important thing here is that you can also call the send_mail.cgi script directly and use it as a web service; for example, using the small JQuery script below:

var mail = {
    subject: "Man walks on the moon",
    message: "Armstrong and Aldrin become the first men on the moon..."

    url: "/send_mail.cgi",
    contentType: "application/x-www-form-urlencoded",
    data: mail, success: function() {
        console.log("Mail sent!");

Now, I will argue that send_mail.cgi is a RESTful web service (!) even if it’s a really poorly designed one and a simple POST /mails service would have been a lot nicer!

If you finish the demanding, yet satisfying task of reading Roy Fielding’s PhD thesis, which defines the REST architectural style, you will see that it says nothing about limiting our REST services to CRUD operations and it also says nothing about limiting ourselves to the collection pattern…

In fact, Fielding later wrote a blog post about the use of the POST method in REST, and said, “As long as the method is being used according to its own definition, REST doesn’t have much to say about it.”  And if we read the HTTP specification we can see that it doesn’t limit the use of POST to adding new items to collections – and if we read the URI specification we can see that it doesn’t limit our URI naming to plural nouns…

So POST /send_mail.cgi is OK from a specification point of view and can be considered RESTful…

So what are you saying?

So what am I saying? Is this the sacking of Rome and we can now all go crazy with POST /add-new-order.cgi and GET /find-my-orders.xml. No laws! No limits!

Of course not. I still think that the Collection Pattern is the right choice for almost all RESTful web services – and it should be the default choice for any new RESTful web service – because it’s so widely adopted and easily recognizable by most API users.

However, there are edge cases where it makes sense to use other patterns, such as the Controller Pattern. For example, if I have a REST service for rockets then one does not simply just launch a rocket (or walk into Mordor!) because you need to provide launch codes and the rocket needs to go through multiple stages before actual take-off – and this goes way beyond just changing the value of a field in the resource representation. So for this scenario I would add a controller subresource:


When breaking with the Collection Pattern I really like the verb-noun naming of the URI, such as launch-rocket. This is without doubts because I read Code Complete way too many times (!) but also because it makes it obvious to the API user that it isn’t a part of the Collection Pattern. On top of that, remember to add a link to controller subresource in the resource representation to make the API user aware that the subresource exists:

    "id": 43,
    "name": "Apollo 11",
    "state": "Ready for launch",
    "_links": {
        "self": {"href": "/rockets/43"},
        "launch-rocket": {"href": "/rockets/43/launch-rocket"} 

This meaning of this post isn’t to say that the Collection Pattern is bad. In fact, it’s the right choice for almost all REST APIs and everybody will love you for using it! 🙂 The purpose is to say that Collection Pattern != REST and you still have some wriggle room for edge cases that doesn’t fit neatly into the Collection Pattern without losing your API’s RESTfulness or the desirable properties that come with this architectural style.