<commit_before>---
layout: post
title: "Keep API Backward Compatibility with Express Gateway"
description: "Express Gateway is an API gateway that sits at the heart of any microservices architecture and that can help you keep your APIs backward compatible."
date: 2018-08-01 10:00
category: Technical Guide, Backend, NodeJS
author:
  name: "<NAME>"
  url: "https://twitter.com/d3dvincent"
  mail: "<EMAIL>"
  avatar: "https://pbs.twimg.com/profile_images/932249086333464576/DacF9HCu_400x400.jpg"
design:
  image: https://cdn.auth0.com/blog/express-gateway/logo.png
  image_bg_color: "#205868"
  bg_color: "#00728E"
tags:
- microservices
- api
- gateway
- compatibility
- javascript
- nodejs
- authentication
- auth
- rest
- apigateway
related:
- 2018-01-11-apigateway-microservices-superglue
- 2017-07-14-getting-a-competitive-edge-with-a-microservices-based-architecture
- 2017-11-15-api-less-scary-approach

---

**TL;DR:** In this article, you will learn how an API gateway can help you retaining API compatibility with **old** clients while _evolving_ the product according to the new needs of your business. If needed, you can find [the code shown here in this GitHub repository](https://github.com/XVincentX/apigateway-playground/tree/gateway-request-response-modification).

---

## Introduction

Systems evolve continously, and so do their WebAPIs. As they represent the interface for external clients to interact with your system, they're the first line **reflecting changes** in your organisation.

Such API changes can happen for a number of reasons. Technological advancements, change in the line of business, important bug fixes and so on.

Chances are you could introduce **breaking** changes in your WebAPI, which in turns means **breaking your clients** that, in order to be operational again, will need to make code changes in their applications and redeploy them so they can use the new API and get back to business.

Some times, changes are **inevitable** and you need to deal with it in a way or in another. However, there's an entire class of problems that can be handled in a different way rather than breaking your API.

Among the possible solutions, we need to cite:

1. An [Hypermedia API](https://medium.com/unexpected-token/how-your-api-could-benefit-from-hypermedia-b62780771ccb) that, with the forewords of putting the understanding in the runtime instead of sharing it ahead of the time, is prepared by definition to handle changes. Clients, if correctly coded, can handle such intrisinc changes in a non-breaking way and adjusting the user experience accordingly.

2. Employ an [API Gateway][express-gateway] to retain the old compatibility while rolling out the new changes. This is a simple yet effetive way to mask the internal changes of your services while keeping the same interface. In such way, you can extend the runaway of your API while evolving your services. You can think about it as the WebAPI version of the [adapter pattern](https://en.wikipedia.org/wiki/Adapter_pattern)

In this article, we're going to explore the second approach. However, Hypermedia APIs are a thing and big companies have been employing such approach for ages.

## Express Gateway to help
<commit_msg>## Why Do I Need Backward-Compatible APIs?<commit_after>---
layout: post
title: "Keep API Backward Compatibility with Express Gateway"
description: "Express Gateway is an API gateway that sits at the heart of any microservices architecture and that can help you keep your APIs backward compatible."
date: 2018-08-01 10:00
category: Technical Guide, Backend, NodeJS
author:
  name: "<NAME>"
  url: "https://twitter.com/d3dvincent"
  mail: "<EMAIL>"
  avatar: "https://pbs.twimg.com/profile_images/932249086333464576/DacF9HCu_400x400.jpg"
design:
  image: https://cdn.auth0.com/blog/express-gateway/logo.png
  image_bg_color: "#205868"
  bg_color: "#00728E"
tags:
- microservices
- api
- gateway
- compatibility
- javascript
- nodejs
- authentication
- auth
- rest
- apigateway
related:
- 2018-01-11-apigateway-microservices-superglue
- 2017-07-14-getting-a-competitive-edge-with-a-microservices-based-architecture
- 2017-11-15-api-less-scary-approach

---

**TL;DR:** In this article, you will learn how an API gateway can help you retaining API compatibility with **old** clients while _evolving_ the product according to the new needs of your business. If needed, you can find [the code shown here in this GitHub repository](https://github.com/XVincentX/apigateway-playground/tree/gateway-request-response-modification).

---

## Why Do I Need Backward-Compatible APIs?

Systems evolve continuously, and so do their WebAPIs. As they represent the interface for external clients to interact with your system, they're the first line **reflecting changes** in your organisation.

Such API changes can happen for a number of reasons. Technological advancements, change in the line of business, important bug fixes, and so on.

Chances are these needs can end up introducing **breaking** changes in your WebAPI, which in turn means **breaking your clients**. Usually, to make these clients operational again, you will need to make changes to their source code and you will need to release new versions of them.

Some times, changes are **inevitable** and you need to deal with them in a way or in another. However, there's an entire class of problems that can be handled in a different way rather than breaking your API.

Among the possible solutions, you can:

1. Use a [Hypermedia API](https://medium.com/unexpected-token/how-your-api-could-benefit-from-hypermedia-b62780771ccb) that, with the forewords of putting the understanding in the runtime instead of sharing it ahead of the time, is prepared by definition to handle changes. Clients, if correctly coded, can handle such intrisinc changes in a non-breaking way and adjusting the user experience accordingly.
2. Employ an [API Gateway][express-gateway] to retain the old compatibility while rolling out the new changes. This is a simple, yet effective, way to mask the internal changes of your services while keeping the same interface. In such way, you can extend the runaway of your API while evolving your services. Think about it as the WebAPI version of the [adapter pattern](https://en.wikipedia.org/wiki/Adapter_pattern).

In this article, you're going to explore the second approach. However, keep in mind that Hypermedia APIs are a good solution and that big companies have been employing such approach for ages.

## Express Gateway to help

{'fraction_non_alphanumeric': 0.07431811216671774, 'fraction_numerical': 0.025743181121667177, 'mean_word_length': 4.592973436161097, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2018619', 'n_tokens_mistral': 1897, 'n_tokens_neox': 1725, 'n_words': 839}