In today’s complex IT environments, integrating multiple systems through a single API is a common requirement. However, managing these integrations effectively requires the right middleware patterns. Middleware acts as the glue that binds different systems together, ensuring they can communicate and work as a unified system. But with so many middleware patterns available, choosing the right one for your use case can be challenging.

In this post, we’ll explore some of the most common middleware patterns for API integrations, detailing their key features, ideal use cases, and when they might become an anti-pattern.

1. API Gateway Pattern

The API Gateway is a popular pattern, especially in microservices architectures. It serves as a single entry point for all client requests, handling tasks such as routing, request/response transformation, and security.

Key Features

• Routing: Directs client requests to the appropriate backend systems.
• Aggregation: Combines responses from multiple services into a single response.
• Security: Manages authentication, authorization, and rate limiting.
• Protocol Translation: Converts protocols as needed, such as from REST to SOAP.

Use Cases

• Simplifying client interactions by exposing a unified API.
• Centralizing security and monitoring for multiple backend services.

When Not to Use / Anti-Pattern

• Monolithic Overhead: If the gateway becomes a bottleneck or a single point of failure, it’s a sign of over-centralization.
• Scalability Issues: In highly scalable environments, an overly complex gateway can hinder performance.
• Complex Routing Logic: Avoid when routing logic becomes too complex, making the gateway difficult to manage.

2. Backend for Frontend (BFF) Pattern

The Backend for Frontend (BFF) pattern is designed to create a specific middleware layer tailored to the needs of a particular frontend, such as web, mobile, or IoT applications.

Key Features

• Tailored APIs: Each frontend gets a custom API, reducing complexity on the client side.
• Orchestration: Handles calls to multiple backend systems and aggregates the results.
• Decoupling: Allows frontend and backend teams to work more independently.

Use Cases

• When different frontends have unique requirements or workflows.
• Optimizing the client experience by minimizing API calls.

When Not to Use / Anti-Pattern

• Duplication of Effort: With many frontends, separate BFFs can lead to duplication and maintenance challenges.
• Over-Complexity: Avoid if business logic is duplicated across multiple BFFs, leading to inconsistencies.
• Small-Scale Projects: Unnecessary complexity for projects with similar frontend requirements.

3. Enterprise Service Bus (ESB) Pattern

An Enterprise Service Bus (ESB) provides a centralized integration platform, managing communication, transformation, and orchestration between multiple systems.

Key Features

• Message Routing: Routes messages between APIs and backend systems.
• Transformation: Converts data formats and protocols between systems.
• Orchestration: Manages workflows that span multiple systems.
• Mediation: Decouples systems, allowing them to communicate through the ESB.

Use Cases

• Ideal for integrating multiple, heterogeneous systems, especially in legacy environments.
• Managing complex message transformation and protocol mediation.

When Not to Use / Anti-Pattern

• Over-Engineering: Introducing an ESB for simple integrations adds unnecessary complexity.
• Single Point of Failure: Without redundancy, the ESB can bring down the entire integration layer.
• Latency and Performance: The additional layers of mediation can introduce significant latency.

4. Service Composition/Orchestration Pattern

In the Service Composition/Orchestration pattern, middleware acts as an orchestrator, coordinating the execution of various services to fulfill a single API request.

Key Features

• Service Aggregation: Combines responses from multiple services.
• Workflow Management: Controls the sequence of service calls based on business rules.
• Error Handling: Manages errors and retries across services.

Use Cases

• When API requests require executing complex business processes across multiple services.
• Scenarios requiring orchestration of microservices to deliver a unified response.

When Not to Use / Anti-Pattern

• Tight Coupling: Orchestration that’s tightly coupled with business processes can make the system brittle.
• Performance Bottlenecks: Over-orchestrating services can slow down response times.
• Simple Use Cases: Overhead from orchestration might be unnecessary for straightforward tasks.

5. Message Broker Pattern

A Message Broker facilitates asynchronous communication between the API and multiple backend systems using message queues or topics.

Key Features

• Decoupling: Allows APIs and backend systems to operate independently.
• Scalability: Supports high throughput by handling messages asynchronously.
• Reliability: Ensures reliable message delivery through persistence and retries.

Use Cases

• Event-driven architectures where APIs trigger processes across multiple systems.
• High-scalability scenarios, such as processing large transaction volumes.

When Not to Use / Anti-Pattern

• Complexity for Simple Tasks: Overkill for straightforward, synchronous communication.
• Message Order Sensitivity: Challenging to maintain strict message order without specialized design.
• Latency Concerns: Not suitable for applications requiring immediate response times.

6. Service Mesh Pattern

A Service Mesh manages service-to-service communication, often used in microservices architectures. It handles traffic management, security, and observability without altering application code.

Key Features

• Traffic Control: Load balancing, routing, and retries across services.
• Security: Manages service-level security policies.
• Observability: Provides insights into service interactions and performance.

Use Cases

• Microservices environments where API requests need efficient routing.
• Advanced network control and security are required for service communication.

When Not to Use / Anti-Pattern

• Over-Engineering: Adds unnecessary complexity to small systems or monolithic applications.
• Operational Complexity: Requires significant operational expertise to manage.
• Performance Overhead: Service meshes can introduce latency due to added layers of communication management.

7. Proxy-Based Middleware Pattern

In a Proxy-Based Middleware pattern, a proxy sits between the API and backend systems, handling communication, routing, and transformation tasks.

Key Features

• Protocol Translation: Converts communication protocols.
• Caching: Caches responses to reduce load and improve performance.
• Load Balancing: Distributes requests across backend systems.

Use Cases

• When you need to abstract the complexity of multiple backend systems from the API.
• Scenarios requiring load balancing, caching, and protocol translation.

When Not to Use / Anti-Pattern

• Transparency Issues: Excessive abstraction can make debugging and monitoring difficult.
• Single Point of Failure: A poorly managed proxy can become a bottleneck.
• Overuse of Caching: Too much caching can lead to stale data or inconsistent responses.

Conclusion

Selecting the right middleware pattern for integrating multiple systems through a single API depends on your specific requirements and constraints. While each pattern has its strengths, it’s crucial to avoid common pitfalls and recognize when a pattern might become an anti-pattern, introducing unnecessary complexity or performance issues.

By carefully considering the use cases and potential downsides, you can design a middleware layer that not only meets your current needs but also scales and evolves with your system over time.

Devcontainers within Visual Studio Code (VS Code) is a powerful concept, being able to create a Docker container with all the tooling and runtime stacks a developer needs to work on a given project, without having to install anything but Docker, VS Code and the VS Code Remote Containers extension.

Essentially devcontainers are VS Code workspace instances that live within the Docker container, when first opening the container the workspace instance is installed and connected to the VS Code UI working in the browser or your local machine.

The above diagram is taken from the VS Code website

Probably you’ve heard a lot about GitHub Codespaces lately, an upcoming feature in GitHub, which essentially uses devcontainers to make its features work.

What has this got to do with continuous integration?

Devcontainers as a concept have little to do with continuous integration (CI), but the Docker container used for the devcontainer to run in does. Your dockerfile contains all the specific versions of tools and runtime stacks you need to do the work.

When moving to CI you then need to make your CI runner build and test the application, meaning you now need to ensure the runner has all the correct tooling with the same versions to do the job correctly. Though having slightly different versions can make little difference, for consistency we want to ensure what the developer is developing with the same tools used in CI.

What are we going to do?

We will create a simple application to run within VS Code devcontainers and set up testing, then move to the CI to run the build and test process there within the Docker container. We will be using GitHub actions for the example, but the concepts work with most modern CI systems.

Before continuing, ensure you have Docker and VS Code installed on to your machine.

Create a devcontainer workspace

We want to build a React web app, so we need a container that has NodeJS installed, we can create our own Dockerfile with all our tools and configurations setup, or pull an existing image from a Docker repo, for this app, we will use the Microsoft standard NodeJS devcontainer.

Firstly, lets create our workspace.

mkdir ci-sample-app
cd ci-sample-app

Next create a folder .devcontainer and inside add a new file .devcontainer.json and inside add the image we want to use as our devcontainer.

{
  "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:0-12"
}

Next we will install the Remote - Containers extension for VS Code. You can install this from the extension’s menu in VS Code or if you have the VS Code path reference set, you can run a command in the root of the project.

code --install-extension ms-vscode-remote.remote-containers

You may need to restart VS Code and once you do, you will be asked if you would like to open the project in a devcontainer.

Click reopen. The first time you do this it will pull the Docker image down from the remote repository, which may take some time.

When everything is complete, everything will still look the same as before, but the VS Code workspace is now running exclusively inside the Docker container.

Creating the React web app

Now we are running in the context of the container, we will create the sample React app and get it running using npm as our package manager.

Using the VS Code terminal, which can be opened from the top menu under Terminal, New Terminal, run the following to create a new React app.

npx create-react-app app
cd app
rm -rf .git # remove git binding as we want to initialize in the root directory
npm start

This will start the React app on port 3000, but if you try to access http://localhost:3000/, you will notice you can’t, this is because we first need to expose the port from within the devcontainer, which can be done inside devcontainer.json.

{
  "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:0-12",
  "forwardPorts": [3000]
}

Inside the .devcontainer.json you can also add VS Code extensions, so every time someone opens the devcontainer they are greeted with the same IDE setup, for example, you may want to add an ESLint extension.

{
  "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:0-12",
  "extensions": ["dbaeumer.vscode-eslint"],
  "forwardPorts": [3000]
}

There are extensions to add Unit Test UI for easy of testing and many, many more.

When editing .devcontainer within the devcontainer, we need to rebuild the container to get the changes.

At the bottom left of VS Code you will see a section containing the words Dev Container.

Clicking this will bring up a menu at the top, select “Remote-Containers: Rebuild Container”.

You should now be able to visit http://localhost:3000/ and see the basic React app up and running.

The sample contains tests, which can be run using npm.

npm test

You can create a release bundle by running npm run build, which will output the content to a folder called build.

CI with GitHub Actions

For this next bit, we will use GitHub Actions to build and test our app using the Docker image used within the devcontainer above.

Create folders in the root of the project as .github\workflows, then create a file called build.yml inside the workflows folder, this will contain our CI code.

We will be using a Linux Hosted machine to do our build, which supports container jobs.

name: Build

on: push

jobs:
  container:
    runs-on: ubuntu-latest
    container: mcr.microsoft.com/vscode/devcontainers/typescript-node:0-12
    steps:

Our pipeline is now defined to pull down the same container we used inside our devcontainer and when it runs the steps (which we will define next), these will be run in the context of the container.

We can run the predefined npm tasks with GitHub Actions, and it will run against our version of npm, or we can run the same commands we have already used to keep consistency.

name: Build

on: push

jobs:
  container:
    runs-on: ubuntu-latest
    container: mcr.microsoft.com/vscode/devcontainers/typescript-node:0-12
    steps:
      - uses: actions/checkout@v2

      - run: npm install
        name: Install npm packages
        working-directory: app
      
      - run: CI=true && npm test
        name: Test React application
        working-directory: app
      
      - run: CI=true && npm run build
        name: Build React app bundle
        working-directory: app

      - uses: actions/upload-artifact@v2
        with:
          name: app
          path: app/build

The last command, will take our build and publish it to the artifacts section of the pipeline run.

Now our code is written we will push it up to a GitHub repo.

git init
git add .
git commit -m "devcontainer CI sample"

Next we will publish to our remote repo (You will want to substitute the GitHub repo with your own).

git remote add origin https://github.com/skilledcookie/devcontainers-and-ci.git
git branch -M main
git push -u origin main

This should automatically run the CI pipeline, which you can see under “Actions” in the repository. See this in our GitHub repo now!

CI in Azure Pipelines example

Azure Pipelines is very similar to GitHub Actions syntax, if you would like to run this example using Azure DevOps, below is the equivalent to the script posted above.

pool:
  vmImage: 'ubuntu-latest'

container: "mcr.microsoft.com/vscode/devcontainers/typescript-node:0-12"

steps:
- bash: npm install
  displayName: Install npm packages
  workingDirectory: app

- bash: npm test
  displayName: Test React application
  workingDirectory: app
  env:
    CI: true

- bash: npm run build
  displayName: Build React app bundle
  workingDirectory: app
  env:
    CI: true

- publish: app/build
  artifact: app
  displayName: Publish to Pipeline Artifacts

More patterns

Above you saw a basic example of how you can use the same Docker container you use in devcontainers in your CI pipelines, but there are other patterns you can use alongside this to add more flexibility to your development workflow.

• Use a Dockerfile to customize your container adding more tools specific to your development and CI workflow, for example adding Terraform to manage your infrastructure.
• Remote Docker repositories like Docker Hub or Azure Container Registry can store and share your private or public images across projects, without the need to build each time.
• Use Docker tags to version your Docker images, so devcontainers and CI can target a specific version, and you can upgrade when you choose, or force the use of the latest tag to ensure everyone is always working with the latest development container.

Exciting times ahead

Overall devcontainers are a very powerful concept and bringing the same container in to your CI pipeline ensures consistency in your development workflow, ensuring you aren’t using different tools or versions of tools in either place.

It will be interesting to see how the devcontainer landscape evolves once GitHub Codespaces is finally released to the public.

Related resources

• Git Hub actions
• Azure Pipelines
• Developing inside a container
• Getting started with Docker
• Getting started with VS Code

Source code

The source code for this post can be found at https://github.com/skilledcookie/devcontainers-and-ci

Comments

Comments can be made on the LinkedIn post here.

Beyond creating standard Azure DevOps Pipelines, we can use templates to manipulate a pipelines definition. We can make custom steps run before or after tasks, or add stages based on certain conditions, or choose to reject a pipeline if certain definitions may or may not exist.

By passing the stages, jobs or steps to a template, we can within the template read the definition, and manipulate it how we see fit.

When passing definitions to a template, you must pass them as a specific data type, you can find a list in the Pipelines runtime parameters documentation.

Data types relevant to the context of manipulating our pipeline definitions with templates include the following.

Passing steps into a template

We will create a template (build-policy.yml), which takes pipeline steps as it’s parameter.

parameters:
- name: stepList
  type: stepList
  default: []

steps: ${{ parameters.stepList }}

This template will just run the given steps. It can be used like the below example.

- template: build-policy.yml
  parameters:
    stepList:
    - script: echo "Hello World 1"
    - script: echo "Hello World 2"

Intercepting and injecting steps

What if we wanted to run our own steps before or after the pipeline steps ran in to the template? We would do this by looping through the steps list and render each step individually, which will allow us to write our own tasks before or after.

Going back to our build-policy.yml example, it would now look like the below.

parameters:
- name: stepList
  type: stepList
  default: []

steps:
- script: echo "Begin running pipeline steps"
- ${{ each step in parameters.stepList }}:
  - ${{ each pair in step }}:
      ${{ pair.key }}: ${{ pair.value }}  
- script: echo "Finished running pipeline steps"

When run the pipeline definition will execute the same as below.

steps:
- script: echo "Begin running pipeline steps"
- script: echo "Hello World 1"
- script: echo "Hello World 2"
- script: echo "Finished running pipeline steps"

Iterate through the steps

In the above example you will notice - ${{ each pair in step }}:, which loops through the top level definition of the steps, which is a little confusing at first, but in reality, it’s pretty simple, which I will try to clarify with an example.

parameters:
  demo:
    - segment: first
      action: test
      value: 1
    - segment: second
      action: run
      value: 2

steps:
- ${{ each demoItem in parameters.demo }}:
  - ${{ each pair in demoItem.segment }}:
    - script: echo "${{ pair.key }} - ${{ pair.value }}"

The above example will output the following.

segment - first
action -  test
value - 1
segment - second
action - run
value - 2

Throwing compile time errors with conditions

When a pipeline is first executed, as part of the normal checks, it will run any logic and perform any substitutions within $ syntax, if this fails for any reason, it will output errors before starting the pipeline run, we can take advantage of this, by providing our own custom exception output.

In the above examples, we use the script task, which depending on the OS will execute in bash or powershell, which isn’t great for reusability, so what if we want to stop our pipeline from using it altogether?

Our first step is to edit our definition and if the script task is detected, throw an error at compile time to stop the pipeline even starting.

parameters:
- name: stepList
  type: stepList
  default: []

steps:
- bash: echo "Begin running pipeline steps"
- ${{ each step in parameters.stepList }}:
  - ${{ each pair in step }}:
      ${{ if eq(pair.key, 'script') }}:
        'script tasks are not allowed!': error
      ${{ if ne(pair.key, 'script') }}:
        ${{ pair.key }}: ${{ pair.value }}  
- bash: echo "Finished running pipeline steps"

There aren’t many options for exceptions in Azure Pipelines, but by providing a message, followed by : error, an exception will be thrown at compile time, which will output your message on screen.

If we want to say throw an error if a condition is met, else it will allow the predefined step to run, we do this with 2 if statements of opposing condition, since there is no if, else syntax within pipelines.

Enforcing standards with extension templates

Lastly what if we wanted to enforce this throughout the pipeline? We do this by changing how we use the template in the pipeline and use the extends syntax.

extends:
  template: build-policy.yml
  parameters:
    stepList:
    - script: echo "Hello World 1"
    - script: echo "Hello World 2"

The extends syntax is used at the top of the pipeline, with any steps, jobs or stages being passed in as parameters, so the template will have access to the entire set of pipeline tasks.

Extension templates can optionally be stored in a shared repository and used within a pipeline of a different repository, which is great for shared company policy templates.

If you moved our templates file in to a repository called automation, we could then implement it by using a repository resource similar to the one below.

resources:
  repositories:
  - repository: automation  # identifier
    type: git 
    name: fabrikam/automation  # repository name (format depends on `type`)
    ref: refs/heads/master  

extends:
  template: build-policy.yml@automation
  parameters:
    stepList:
    - script: echo "Hello World 1"
    - script: echo "Hello World 2"

Things to be aware of

When consuming extension templates from a shared repository, you need to be aware of the following;

1 - Local templates must have @self on the end when being imported in to the pipeline definition.

Before using an extension template.

# ci/azure-pipelines.yml
...
steps:
- template: templates/build.yml

After applying an extension template.

# ci/azure-pipelines.yml
...
steps:
- template: ci/templates/build.yml@self

2 - Local template imports now become relative to $(System.DefaultWorkingDirectory), instead of the pipeline directory (shown in the above example).

3 - If you have other templates you wish to use inside the extension template context, from the shared repository, they will need to be included relative to the extension templates folder.

If we have an extension template in a shared repository, lets say extensions/policy.yml and a reusable build template in the same repository templates/build.yml, then in the pipeline, we would use them together as follows.

resources:
  repositories:
  - repository: automation  # identifier
    type: git 
    name: fabrikam/automation  # repository name (format depends on `type`)
    ref: refs/heads/master  

extends:
  template: extensions/policy.yml@automation
  parameters:
    stepList:
    # relative to extensions folder
    - template: ../templates/build.yml@automation

Powerful stuff

By using the examples above in regard to steps (stepList), you can apply the same processes over jobs (jobsList) and stages (stageList) too, and can get even more complex by iterating stages and their jobs, or even the jobs and their steps and apply your own logic in regard to the defined pipeline.

Overall expressions and templates within Azure Pipelines are very powerful, allowing you to enforce your own standards and checks, allowing compliance and security to be built in by default in to every new pipeline by sharing them.

What kind of things can I do?

There are many use cases for manipulating the pipeline using templates, avoiding you having to keep repeating your code in every pipeline, or just to enforce compliance. Here is just a few scenarios to get you started.

• Pushing notifications to remote systems when a new stage or deployment job starts or ends, for auditing or updates to service tickets.
• Avoid certain pipeline tasks being used (like the script example discussed above), to ensure a consistent approach, or to help with security concerns.
• Restrict deployments to specific branches to enhance security.
• Injecting steps before or after steps defined in the pipeline run, maybe to get the environment in to a secure or useable state before a pipeline executes its steps.
• Enforcing a branching strategy by failing pipelines before they run if the correct branch isn’t used. You could also check a pull requests source and target branches at runtime and fail if it’s not a correct transition.
• Checking with remote services before deploying to ensure certain checks have been passed before continuing.

There are a lot more things you could do, but the main point is that these templates are abstracted from the pipeline. This has the benefit’s of being repeatable and the consumer doesn’t need to care about what, or how they are doing something, it should simply do it.

Related resources

• Azure Pipelines Expressions
• Azure Pipelines Templates
• Azure Pipelines Schema Reference
• Azure Pipelines Runtime Parameters