carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby and Python.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Staff Developer Advocate

Carla Urrea Stabile

In this blog post you’ll learn about different API Gateways: Zuplo, Kong, and Apache APISIX, and how each one could work best for a service that uses Fine-Grained Authorization.

Using an API Gateway with Fine-Grained Authorization

Nesh Popovic

As a Developer and Solutions Engineer for the past 20+ years, I've been involved in developing and selling secure and robust software solutions. When not helping my sales team deal with the complexities of software platforms, you can usually find me playing pickleball, basketball or backgammon.

Principal Solutions Engineer - CIAM

Learn how to set up an Amazon API Gateway and secure the REST API with Okta Customer Identity Cloud (CIC) Adaptive MFA Risk Score

Protecting REST APIs Behind Amazon API Gateway Using Okta

fauna_author

Technology focused business professional with experience in Sales & BD, Solutions Architecture and Software Development. Armed with a top-tier MBA and extensive customer-facing experience, I combine technical and business expertise to converge business requirements with technology. 
<br>
My experience in the art of pre-sales is combined with practical hands-on expertise in software SDLC, cloud architecture, containers, networking, APIs and gateways. A trusted advisor, I have the proven capacity to win over the most technically discerning customers and build long lasting relationships.

Head of Solution Architecture at Fauna Inc.

Zee Khoo

In this tutorial, we’ll explore architecting REST APIs in a fully serverless manner by leveraging Fastly’s Compute@Edge, Fauna, and Auth0

Building an Edge API Gateway with Fauna and Securing It with Auth0

joydip-kanjilal

I received the Microsoft MVP award in ASP.NET for six consecutive years from 2007 to 2012. I'm a software architect, author, and speaker. I've more than 25 years of experience in the software industry, with more than 18 years in Microsoft .NET and its related technologies. These days I'm exploring AI and Machine Learning.

Software Architect and Advisor

Joydip Kanjilal

Learn what an API Gateway is and how to build yours in ASP.NET Core by using Ocelot.

Implementing an API Gateway in ASP.NET Core with Ocelot

john-brennan

John is an R&D Content Engineer at Auth0. He has nearly a decade’s experience in full-stack software development in a variety of environments, languages, and frameworks. He relishes the challenge of learning hard-to-grasp technical concepts and helping others understand them in a clear, concise manner. His current technical interests are in API design and scalability, Ruby on Rails, accessibility, single-page app architecture, and the ever-changing JavaScript ecosystem. When he's not working, John is usually cooking, doing creative writing, running, or wrangling a toddler.

R&D Content Engineer

John Brennan

Learn about securing HTTP APIs built on AWS API Gateway using JWT authorization

Securing AWS HTTP APIs with JWT Authorizers

vincenzo-chianese

Vincenzo Chianese is an Italian Software Developer focused on Web APIs and User Interfaces. He has been working for the last years in API companies such as Apiary, Oracle, LunchBadger, Stoplight. Currently, he is working for Microsoft to help move Microsoft Graph forward and authored some open-source tools in the market (Prism, Express Gateway).

API Architect

Vincenzo Chianese

Learn how this API gateway, built on Express.js, can help you retain API compatibility with old clients while evolving the product according to new business needs.



**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).

<include src="TweetQuote" quoteText="Learn how to keep your APIs backward compatible while being able to implement new features, fix bugs, and so on."/>

---

## 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 organization.

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.

Sometimes, 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 intrinsic changes in a non-breaking way and adjust 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.

![How an Express gateway works.](https://images.ctfassets.net/23aumh6u8s0i/7Ghx1UORjLYzZkATKmCtNb/3912c09624d91813c91bfca8d7a7fc9c/express-gateway)

## Express Gateway to the Help

It turns out [Express Gateway][express-gateway] is a **perfect** candidate for such task. In this example, you will learn two important things:

- how you can change the shape of a request's body coming into a service;
- and how you can modify the response body to keep the same interface exposed to the clients.

### Depicting the Problem

Imagine a simple use case where keeping an API compatibility with the clients is important (probably any note-worthy app needs this). Suppose you have a service, coded by your internal development team, that exposes an API able to return a customer by its ID on HTTP GET requests. The response would be similar to this:

```json
{
  "customerId": "123456789",
  "name": "Clark",
  "surname": "Kent"
}
```

Also, your API would accept new customers with a `POST` request using the following payload:

```json
{
  "name": "Clark",
  "surname": "Kent"
}
```

This operation would then return the created customer with a generated `customerId` and the operator that created such user:

```json
{
  "customerId": "123456",
  "createdBy": "vncz"
}
```

Suppose now that, given your business is growing, you decide that it makes sense to **replace your homemade customer service** with a third-party cloud service that's offering better customer management capabilities that perfectly fits your company needs.

Most likely, the offered API, as well as the provided features, will differ in multiple parts. For example, the URL space is going to be different as well as the accepted and returned payloads.

In this example, suppose the new service has an endpoint on `/v1/cust` (instead of `/customers`) and, instead of accepting a `name` and `surname` properties, it requires a unique `fullname` property. Also, as it's an external service, it does not include any `createdBy` property, as it's a property that exists exclusively in your system.

While these changes most likely make sense for your internal clients (due to business requirements for example), your existing third-party clients do not care that much about this change. So, while willing to migrate at a certain point in the future, flipping directly the switch would not be an option.

### Keeping the Legacy API Intact Using Express Gateway

It turns out that an [API Gateway][express-gateway] can solve this problem for you. Being an intermediate layer between the public interface **AND** the internal services, an Express Gateway can manipulate the requests and the responses during their journey.

Here's what you would need to do to set up a gateway:

- You would need to configure the [`proxy`][proxy] policy so that the request to the old endpoint get routed to the new, correct internal services.
- You would need to configure the `bodyModifier` policy to modify the request's body so that the new customer service can consume it. In the same way, you would use the same policy this time to modify the response object to make sure the `createdBy` property is correctly added.

### Installing Express Gateway

To solve these problems with Express Gateway, you would install and use a beta version of the framework. This version will most likely land in the `master` branch (thus as an official version) soon (the team supporting Express Gateway is still in the process of discussing some internal requirements, so they weren't able to make it happen officially yet).

```bash
npm install expressgateway/express-gateway#feat/proxy-events
```

### Set up Pipelines to Proxy Objects Back and Forth

Then, after installing this beta version, you would set up two pipelines that would proxy the requests to the new `/cust/v1` endpoint:

```yaml
apiEndpoints:
  customers:
    path: '/customers*'
serviceEndpoints:
  v1Cust:
    url: 'https://cool.Cloud.service/v1/cust'
policies:
  - proxy
  - bodyModifier
pipelines:
  customers:
    apiEndpoints:
      - customers
    policies:
      - proxy:
        - action:
            serviceEndpoint: v1Cust
```

### Using Express Gateway to Change the Request and Response Body

After that, you would use the `bodyModifier` policy to modify request/response payloads so they conform to the new service API.

```yaml
      - bodyModifier:
        - action:
            request:
              add:
                - name: fullname
                  value: "req.body.name + ' ' + req.body.surname"
              remove:
                - name: name
                - name: surname
            response:
              add:
                - name: createdBy
                  value: "req.user.id"
```

It should be easy to understand what's going on in the configuration above. This is concatenating the `name` and `surname` properties from the current request body and forming a new `fullname` property out of it. Once that's done, it removes these properties as they're not required by the new service.

Then, this configuration is performing a similar task for the response. That is, it is adding back the `createdBy` property based on the current user registered in the gateway.

If you put your system up now, you would be able to test the new features with the following command:

```bash
curl -X POST http://localhost:9876/customers/ -H "Content-Type: application/json" -d '{"name":"Clark", "surname": "Kent"}'
```

The system, despite the code changes in the internal service, would still be working (and, more importantly, responding) in the same way it did before.

<include src="asides/ExpressGateway" />

## Conclusions

It is important to note that this approach would keep the whole object in memory and would be taking the burden of parsing it. In case of huge payloads (several MBs), a more efficient way would be to parse the content as a stream, using [JSONStream](https://github.com/dominictarr/JSONStream) for example. This article won't explore this solution, but it should be the way to go in case you're expecting huge JSON objects. For small payloads the JSON parsing, although sync, the default solution wouldn't take more than 1ms.

<include src="TweetQuote" quoteText="Tools like Express Gateway can be life savers when developing apps based on the microservice approach."/>

[express-gateway]: https://express-gateway.io
[proxy]: https://express-gateway.io/docs/policies/proxy


Keep API Backward Compatibility with Express Gateway

Express Gateway is an API gateway that sits at the heart of any microservices architecture, securing your microservices and exposing them through APIs.



**TL;DR:** In this tutorial, I'll show you how an API gateway can collect application specific metrics for you.
You can get [the code example in this GitHub repository](https://github.com/XVincentX/express-gateway-prometheus-metrics-example).

---

## Introduction

Unless you're building a proof of concept or an application that's not aiming to reach production, you definitely want to add **monitoring** and **metrics** to your system. In this installment, we're going to look how **Express Gateway** can help you to add application specific metrics and expose them through an HTTP endpoint that can be queried by an external service, such as [Prometheus][prometheus-homepage].

<include src="TweetQuote" quoteText="Monitoring and metrics are an important part of your system."/>

## Express Gateway to Rescue

Express Gateway is an API gateway that sits at the heart of any microservices architecture (regardless of what language or platform is being used), **securing** the different pieces and exposing them through **APIs**. All these magic works by using [Node.js](https://nodejs.org), [ExpressJS](https://expressjs.com/), and [Express middleware](https://expressjs.com/en/guide/writing-middleware.html).

![Express Gateway Diagram](https://images.ctfassets.net/23aumh6u8s0i/SsB12EeBdofDnsa69tJzv/26a9fd4972def879fd3181e203d91b11/express-gateway-diagram)

Express Gateway centralizes all the application configuration for the API use case into one YAML (or JSON) file. Within the YAML file there is an easy to understand description of what is configured and how.

Express Gateway entities, like _policies_, _pipelines_, _conditions_, and _actions_ wrap around Express middleware to make it **dynamic**. Any Express middleware can be plugged into Express Gateway to take advantage of its dynamic capabilities. It also features a hot-reload mechanism so you can change its configuration without having to restart the gateway at all.

## Writing a Plugin for Express Gateway

Express Gateway comes with a plugin framework used to extend the Express Gateway core.

The plugin framework enables anyone to take **Express middleware** and integrate them into Express Gateway as plugins. Express Gateway provides a declarative way to take advantage of Express middleware to be driven centrally and executed dynamically.

We're going to leverage such framework in order to build a plugin that'll hook in our HTTP responses and collect the information we need.

### Scaffold a Plugin

A plugin is nothing more than a JavaScript object that you export. It's shape is described in detail [in the documentation][plugin-shape]

```javascript
module.exports = {
  init: function (pluginContext) {

  },
}
```

In our case, we will create a plugin that:

1. Exposes a policy that will hook in the [response][express-response], collecting information in
[Prometheus format][prometheus-format].
2. Extend the [Admin API][admin-api] to expose an additional endpoint that will serve all the collected information.

#### What Metrics Are We Going to Collect?

There are a lot of ways to slice and dice metrics. They may vary according to your needs.

In this example, we will label all the responses that are on the way to the client according to:

* Success/Failed responses (discerned on the status code).
* The status code itself.
* The consumer id (if the request is authenticated).
* The [API Endpoint][apiendpoint] that triggered the Gateway.

#### What format do we expose the metrics?

To leverage the existing tooling around, we will expose the collected metrics in the [Prometheus Text Based Wire Format][prometheus-format]. In this way, we can **leverage the tools** that are already on the space to push and visualize the information, such as [Grafana][grafana].

```javascript
const metrics = require('prom-client');

const statusCodeCounter = new metrics.Counter({
  name: 'status_codes',
  help: 'status_code_counter',
  labelNames: ['type', 'status_code', 'consumer', 'apiendpoint']
});

module.exports = {
  version: '1.0.0',
  policies: ['metrics'],
  init: (pluginContext) => {
    pluginContext.registerAdminRoute((app) => {
      app.get(pluginContext.settings.endpointName, (req, res) => {
        if (req.accepts(metrics.register.contentType)) {
          res.contentType(metrics.register.contentType);
          return res.send(metrics.register.metrics());
        }

        return res.json(metrics.register.getMetricsAsJSON());
      });
    });

    pluginContext.registerPolicy({
      name: 'metrics',
      policy: ({ consumerIdHeaderName }) => (req, res, next) => {
        res.once('finish', () => {
          const apiEndpoint = req.egContext.apiEndpoint.apiEndpointName;
          const consumerHeader = req.header(consumerIdHeaderName) || 'anonymous';
          const statusCode = res.statusCode.toString();
          const responseType = res.statusCode >= 200 && res.statusCode < 300 ? 'SUCCESS' : 'FAILED';
          statusCodeCounter.labels(responseType, statusCode, consumerHeader, apiEndpoint).inc();
        });

        next();
      }
    });
  }
};

```

Let's go through the code and see the relevant parts:

```javascript
const statusCodeCounter = new metrics.Counter({
  name: 'status_codes',
  help: 'status_code_counter',
  labelNames: ['type', 'status_code', 'consumer', 'apiendpoint']
});
```

Here we're declaring a new Prometheus Counter called `status_code` that will track all the responses and categorize
them based on the declared labels (`['type', 'status_code', 'consumer', 'apiendpoint']`):

```javascript
pluginContext.registerAdminRoute((app) => {
  app.get(pluginContext.settings.endpointName, (req, res) => {
    if (req.accepts(metrics.register.contentType)) {
      res.contentType(metrics.register.contentType);
      return res.send(metrics.register.metrics());
    }

    return res.json(metrics.register.getMetricsAsJSON());
  });
});
```

This part of code is registering a new [route][admin-route-plugin] that will expose all the collected metrics. According to the `Accept` header, we're either returning the data in Prometheus format as JSON or in text format. The external tool collecting the data (such as InfluxDB or a Prometheus server) will query this endpoint **periodically** to grab the latest updates.

*Note:* Prometheus also supports [data pushing](https://prometheus.io/docs/instrumenting/pushing/) instead of polling it periodically. If you go in this way, you can **avoid to expose an endpoint** at all. Based on your requirements (such as security) you may opt for this other option.

```javascript
pluginContext.registerPolicy({
  name: 'metrics',
  policy: ({ consumerIdHeaderName }) => (req, res, next) => {
    res.once('finish', () => {
      const apiEndpoint = req.egContext.apiEndpoint.apiEndpointName;
      const consumerHeader = req.header(consumerIdHeaderName) || 'anonymous';
      const statusCode = res.statusCode.toString();
      const responseType = res.statusCode >= 200 && res.statusCode < 300 ? 'SUCCESS' : 'FAILED';
      statusCodeCounter.labels(responseType, statusCode, consumerHeader, apiEndpoint).inc();
    });

    next();
  }
});
```

Then, we export a new policy that will register an event handler once the response is terminated. Here we can now **inspect** all the response as well as request details that will populate our labels.

*Note:* [`egContext`][egcontext] is an Express Gateway specific object that contains additional information on the request that's being handled.

## Put it in production

We have our plugin ready to be used. Now we have to install it in our Gateway and enabled it.

Express Gateway plugins are nothing more than **NPM packages**, so we can simply publish our package to the registry and then install it using the command line.

For this tutorial, I've already published a plugin called `express-gateway-prometheus-metrics-example` with the exact same code we saw above. Hence, we can install the plugin directly by simply typing `eg plugins install express-gateway-prometheus-metrics-example`

*Note:* Express Gateway can also load [plugins inline][inline-load]. This is useful when you want to test them before publishing them. In this case, you could point the `package` property to our `index.js` file.

Now let's modify our [`gateway.config`][gateway-config] and configure a policy that will take advantage of such policy:

```yaml
http:
  port: 8080
admin:
  port: 9876
apiEndpoints:
  api:
    host: '*'
serviceEndpoints:
  httpbin:
    url: 'http://httpbin.org'
policies:
  - proxy
  - metrics
pipelines:
  - name: basic
    apiEndpoints:
      - api
    policies:
      - metrics:
      - proxy:
          - action:
              serviceEndpoint: httpbin
              changeOrigin: true
```

## See it live

Let's spin up the gateway and throw some requests to it:

```bash
$ ab -n 20 http://localhost:8080/
```

Once the command is terminated, we can now query our metrics endpoint to see what happened with such requests:

```bash
$ curl http://localhost:9876/metrics
# HELP status_codes status_code_counter
# TYPE status_codes counter
status_codes{type="FAILED",status_code="502",consumer="anonymous",apiendpoint="api"} 15
status_codes{type="SUCCESS",status_code="200",consumer="anonymous",apiendpoint="api"} 5
```

You can see we received back the Prometheus metrics with all the data we collected.

## Byproduct — Use JSON Schema to validate your parameters

Express Gateway relies on **JSON Schemas** to make sure all the configurations that goes in its funnel it's correct.

You can leverage the same mechanism to specify the **required** parameters, good defaults and **validation** rules for your plugin.

In our case, for instance, it's pretty clear that the Admin API path where the metrics will be exposed is **mandatory**; also we might want to configure the header where the consumer id information is stored.

With these two requirements in mind, we can write something like this:

```javascript
module.exports = {
  version: '1.0.0',
  policies: ['metrics'],
  schema: {
    $id: 'http://express-gateway.io/plugins/metrics.json',
    type: 'object',
    properties: {
      endpointName: {
        type: 'string',
        default: '/metrics'
      }
    }, required: ['endpointName']
  },
  init: function (pluginContext) {
    pluginContext.registerAdminRoute((app) => {
      // admin route code
    });

    pluginContext.registerPolicy({
      name: 'metrics',
      schema: {
        $id: 'http://express-gateway.io/policies/metrics.json',
        type: 'object',
        properties: {
          consumerIdHeaderName: {
            type: 'string',
            default: 'eg-consumer-id'
          }
        }, required: ['consumerIdHeaderName']
      },
      policy: ({ consumerIdHeaderName }) => (req, res, next) => {
        // policy code
      }
    });
  }
};

```

Thanks to this small addition, the gateway will **validate** the provided parameters against the schema and will
refuse to load the plugin if the validation does not pass.

<include src="asides/ExpressGateway" />

## Conclusions

Metrics are **hard**. In a Microservices context, it's even **harder**. In this installment we discovered how to leverage the shared **middleware** (our API gateway) to collect data **without** having to modify the services' code at all, and have a **centralized** way to push and display these.

<include src="TweetQuote" quoteText="Metrics are hard. In a Microservices context, it's even harder. See how Express Gateway and Auth0 can help you with that"/>

[plugin-shape]: https://www.express-gateway.io/docs/plugins/plugin-development/
[express-response]: http://expressjs.com/en/4x/api.html#res
[admin-api]: https://www.express-gateway.io/docs/admin/#markdown
[apiendpoint]: https://www.express-gateway.io/docs/configuration/gateway.config.yml/apiEndpoints/#markdown
[prometheus-format]: https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md
[grafana]: https://grafana.com/plugins?type=datasource
[admin-route-plugin]: https://www.express-gateway.io/docs/plugins/route-development/#exporting-admin-routes-to-plugin
[egcontext]: https://www.express-gateway.io/docs/policies/customization/eg-context/
[inline-load]: https://github.com/XVincentX/express-gateway-prometheus-metrics-example/blob/master/gateway/config/system.config.yml#L9
[gateway-config]: https://www.express-gateway.io/docs/configuration/gateway.config.yml/
[prometheus-homepage]: https://prometheus.io/


Application Specific Metrics with Express Gateway

Express Gateway is an API Gateway that sits at the heart of any microservices architecture, securing your microservices and exposing them through APIs.



**TL;DR:** In this tutorial, I'll show you how an API Gateway can be a great tool when you have multiple
microservices that need to share multiple tasks. You can get the code example [here](https://github.com/XVincentX/apigateway-playground).

---

## Introduction

[Microservices](https://auth0.com/blog/an-introduction-to-microservices-part-1/) is an architectural style with the basic idea of **decomposing** a system in a collection of services, each one implementing a particular capability/feature of the system itself based on business, technical, and other requirements.

[This has several benefits compared to a monolithic approach](https://auth0.com/blog/getting-a-competitive-edge-with-a-microservices-based-architecture/):

* It enables the **continuous delivery** of large, complex applications by deploying the singular pieces **independently**.
* It enables to select the framework and the programming language that you think it's the best for the job. You can use the latest technologies on a microservice while keep the other parts in legacy mode.
* It improves your teams agility, the ability to iterate on a small, focused piece of functionality quickly and to see results.
* It improves the resiliency of your system because a crash of a microservice **does not halt** your entire system (you can gracefully degrade the user experience).

The above points can be summarized with two keywords: **independence** and **isolation**.

This concept has been riding high during the last years with [blog posts](https://auth0.com/blog/tags/microservices/), articles, [websites](http://microservices.io), and even dedicated conferences although this is nothing really new—but rather a culmination of **best practices** in the modern web era, pushed by a tech giant that felt the need almost [ten years ago](http://www.zdnet.com/article/soa-done-right-the-amazon-strategy/).

Most of the time we don't necessarily have the same web scale, but we can benefit anyway from the paradigm of microservices.

## Challenges

The challenge though is that with microservices the knowledge is spread among multiple little pieces. However, on the other hand, the end game of your application is, most of the time, the exposure of what you're building through an **uniform API**.

So, we have two sides of the same coin: on one side, we want to break up our app into a set of services and [evergreen](https://blog.juriba.com/evergreen-it-concept-or-reality) them; on the other, we still want to offer an uniform experience.

Suppose you need to create a `Coffee` order system that will let people, registered as `Customers`, request for a coffee through an `Order`.

After a bunch of meetings, everybody in the company agrees that the `User` and registration part of your application will be written in JavaScript and run on [Node.js](https://nodejs.org/en/), while the `Order` system will be written in Go. Among the technical requirements, you want all the requests must be authenticated and, in order to prevent flooding, you want to put a [rate limiting policy](https://auth0.com/docs/connections/database/rate-limits).

Now, with such requirements, a couple of questions stand:

1. Writing **idiomatic** JavaScript is different than writing idiomatic Go. According to the programming language and the framework you're using the API you're exposing in Go might be **completely** different with regards to the other one exposed from the JavaScript microservice. How do you make sure that the final API—intended as the the whole surface exposed by your application—is _uniform_ and _consistent_?
2. _Rate limiting_, _authentication_, _authorization_, and a bunch of other stuff are things that should be shared across multiple microservices in your organisation. If you re-implement these things in each single microservice, you are **duplicating** the code at first, but more importantly you have two different pieces of software to maintain. This will mean that you will also need to make sure they behave in the same way (that's not trivial, since you could be potentially using two libraries for that).

## Solution

It turns out that, no matter the way you're doing microservices (whether you're dividing your system by business features, by domain, or coming up with a microservice architecture starting from your data), there are parts of them that are sharing functionalities.

[Microservices need a **superglue** and that glue is an **API Gateway**](https://auth0.com/blog/an-introduction-to-microservices-part-2-API-gateway/).

## API Gateway

An _API Gateway_ is a centralized middleware that encapsulates the internal system architecture and provides an API that can be shaped based on real client needs rather than simply returning what the particular microservice is sending you back. These gateways are effectively implementing the [**facade pattern**](https://en.wikipedia.org/wiki/Facade_pattern) in the microservices world.

API Gateway can have other responsibilities such as _authentication_, _monitoring_, _load balancing_, _caching_, _request shaping and management_, and _static response handling_.

## API Gateway in Practice

Let's move from theory to practice and see how to configure an API Gateway to serve our needs.

Let's suppose that we have `Customer` and `Order` microservices listening to `http://customers` and `http://orders` respectively. Using [Docker](https://docker.com) or [Kubernetes](https://kubernetes.io) achieving such scenario should be fairly easy.

We will configure an instance of an API Gateway that will sit on the edge of our system. This gateway will serve as a router for our microservices, but we'll also move some shared logic from the microservices to it. This will enable our applications to focus on the business logic.

This gateway will also throttle all the requests based on clients' IP addresses and make sure that all the
requests are authenticated based on a **JWT** that _Auth0_ is going to provide. [Auth0 will work as our **system of record** for our users](https://auth0.com/blog/360-view-of-customer-by-managing-identity/).

There are multiple API Gateways on the market. Some of them are offered by big software companies as a managed hosted solution and others are open source products. Of course, you can technically write your own solution too, but why reinvent the wheel? Instead, let's take advantage of [Express Gateway](https://express-gateway.io).

## Meet Express Gateway

Express Gateway is an API Gateway that sits at the heart of any microservices architecture (regardless of what language or platform you're using), **securing** the different pieces and exposing them through **APIs**. All these magic works by using [Node.js](https://nodejs.org), [ExpressJS](https://expressjs.com/), and [Express middleware](https://expressjs.com/en/guide/writing-middleware.html).

![Express Gateway Diagram](https://images.ctfassets.net/23aumh6u8s0i/SsB12EeBdofDnsa69tJzv/26a9fd4972def879fd3181e203d91b11/express-gateway-diagram)

Express Gateway centralizes all the application configuration for the API use case into one YAML (or JSON) file. Within the YAML file there is an easy to understand description of how and what is configured.

Express Gateway entities, like _policies_, _pipelines_, _conditions_, and _actions_, wrap around Express middleware to make it **dynamic**. Any Express middleware can be plugged into Express Gateway to take advantage of its dynamic capabilities. It also features an hot-reload mechanism so you can change its configuration without having to restart the gateway at all.

### Hands On

Installing [Express Gateway](https://express-gateway.io) is dead simple:

`~$ npm i -g express-gateway`

This will install the command line `eg` in your system, so you can now bootstrap a new gateway instance:

```shell
~$ eg gateway create
? What\'s the name of your Express Gateway? eg-example
? Where would you like to install your Express Gateway? eg-example
? What type of Express Gateway do you want to create? Getting Started with…
     created package.json
     created server.js
      ...  To start eg-example, run the following commands:
     cd eg-example && npm start
```

Next, change the working directory to `eg-example` (`cd eg-example`) and modify the [`gateway.config.yml`](https://www.express-gateway.io/docs/configuration/gateway.config.yml/) file. This is the file that controls your gateway’s behavior. For a complete configuration reference, you can see the [documentation](http://www.express-gateway.io/docs/).

```yml
http:
  port: 8080
apiEndpoints:
  customers:
    host: customers.company.com
  orders:
    host: orders.company.com
serviceEndpoints:
  customers:
    url: 'http://customers'
  orders:
    url: 'http://orders'
policies:
  - jwt
  - proxy
  - rate-limit
pipelines:
  customers:
    apiEndpoints:
      - customers
    policies:
      - rate-limit:
        - action:
            max: 1
            windowMs: 1000
      - jwt:
        - action:
            secretOrPublicKeyFile: ./key/pubKey.pem
            checkCredentialExistence: false
      - proxy:
          - action:
              serviceEndpoint: customers
              changeOrigin: true
  orders:
    apiEndpoints:
      - orders
    policies:
      - rate-limit:
        - action:
            max: 1
            windowMs: 1000
      - jwt:
        - action:
            secretOrPublicKeyFile: ./key/pubKey.pem
            checkCredentialExistence: false
      - proxy:
          - action:
              serviceEndpoint: orders
              changeOrigin: true
```

Let's go through the main part of the current configuration. The gateway will listen for HTTP requests on port `8080` (you might want to change it to `80` when going into production). Then, we have defined two **pipelines** (one per microservice) where we have enabled the [rate limit policy](https://www.express-gateway.io/docs/policies/rate-limiter) and the
[JWT](https://www.express-gateway.io/docs/policies/jwt) verification policy.

> **Note:** the configuration is shown in a extended form for clarity. However, it can be shortened by using [YAML references](http://blog.daemonl.com/2016/02/yaml.html).

> **Note:** if you want to test this locally, you'll need to make sure that `company.com` domain points to your local machine. This can be achieved by using [`dnsmasq`](http://www.thekelleys.org.uk/dnsmasq/doc.html) or by [modifying your hosts file](https://support.rackspace.com/how-to/modify-your-hosts-file/), putting both `customers.company.com` **and** `orders.company.com` to point to `localhost`. Another alternative would be to manually put the `HOST` header to the correct value while issuing requests.

### Configure the Client and the User in Auth0

Let's now configure Auth0 to work as our **system of record** for users and **issue JWTs** for them. If you don't already have an Auth0 account, <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one now</a>.

From the [Auth0 management dashboard](https://manage.auth0.com/), click on the **APIs** menu item, and then on the **Create API** button. You will need to give your API a name and an identifier. The name can be anything you choose, so make it as descriptive as you want. The identifier will be used to identify your API, this field cannot be changed once set.

For our example, I'll name the API **billings** and identify it as `http://orders`. I'll also leave the signing algorithm as `RS256` and click on the **Create API** button.

![Creating billings API on Auth0](https://images.ctfassets.net/23aumh6u8s0i/2wgySpoX1QsiKHgITJWh11/646b7364760f17fdbb9800a280045c18/create-auth0-api)

Now point your browser to `https://yourAPI.auth0.com/pem` (where `yourAPI` is the Auth0 domain that you chose when creating your account) and download the **public key** file. This is the key that we will
use to verify that the JSON Web Tokens (JWTs) issued by Auth0 are valid. Save it as `pubKey.pem` and place it in the same directory specified in `secretOrPublicKeyFile` parameter of the `jwt` policy (that is, in a directory called `key` in the project root).

The API Gateway has now been configured correctly to handle the scenarios.

### Test Drive

Start the gateway using `npm start` in the project root. Once running, let's try to issue a couple of requests to it:

```shell
$ curl http://customers.company.com:8080 & curl http://customers.company.com:8080
$ [1] 4495
$ Unauthorized
$ [1]+  Done
$ Too many requests, please try again later.
```

You can see that the first request has been denied with `Unauthorized` status. That's because we didn't
provide any JWT with the request, so it didn't go through.

Moreover, the second request has been refused by the rate limiting policy, without event arriving to the
**authentication** phase. Policies are executed following the definition order in the configuration file.

Now grab any HTTP client and let's configure it to start an OAuth 2.0 authorization process against our API hosted in Auth0. We can grab all the necessary parameters going on _Applications_ -> _billings (Test Application)_ -> _Settings_ -> _Advanced Settings_ -> _Endpoints_

In my case, I am going to use `curl`, but you can use the one you prefer:

```bash
curl --request POST \
  --url https://bkrebs.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"my-client-id-copied-from-auth0-application",
    "client_secret":"my-super-secret-copied-from-auth0-application",
    "audience":"http://orders",
    "grant_type":"client_credentials"
}'
```

Now, by simply copying the `access_token` attribute from the response, we will be able to communicate with the API through Express Gateway (you can verify the returned token by using [JWT.io](https://jwt.io/#debugger)). This is the token to be used in order to access the protected resource. So, just try to issue requests making sure that the token is now sent as a `Bearer` Authorization to the endpoint. The response should hopefully be `200`.

```bash
export JWT="ey...the-rest-of-the-token"
curl -H "Authorization: Bearer "$JWT http://customers.company.com:8080
```

## Conclusions

Thanks to [Express Gateway](https://express-gateway.io), we have moved two shared concerns (authentication and rate limiting) from the microservices to a centralized middleware that—no matter how many microservices we're going to have—it is going to behave in a consistent way.

We can now safely remove the code handling that from our microservices and assume that, if they're receiving a request, it's both **authenticated** and it passed the **rate-limit** checks. You now have **guarantees**.

However, this is just the tip of the iceberg.

The benefits of an API Gateway do not stop here. In this example, we've shown how it can make some checks on **inbound** requests, but it can also be used to modify the **outbound** responses.

In the initial part of the article, we were talking about the uniform API. An API Gateway could transform the response coming from a particular microservice so that the returned payload is consistent with the other microservices, even though the original data is shaped in a different way. Hopefully, we will explore this in a future article.

In the meantime, you can see some other interesting use cases on [Express Gateway website](http://www.express-gateway.io/resources/).


API Gateway: the Microservices Superglue

001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

Learn about API gateways and how they work in a microservice-based architecture



In this post in the microservices series we will talk about API gateways and how they can help us solve some important concerns in a microservice-based architecture. We described these and other issues in our [first post](https://auth0.com/blog/2015/09/04/an-introduction-to-microservices-part-1/) in the series.

-----

## What is an API gateway and why use it?

In all service-based architectures there are several concerns that are shared among all (or most) services. A microservice-based architecture is not an exception. As we said in the first post, microservices are developed almost in isolation. Cross-cutting concerns are dealt with by upper layers in the software stack. The API gateway is one of those layers. Here is a list of common concerns handled by API gateways:

- Authentication
- Transport security
- Load-balancing
- Request dispatching (including fault tolerance and service discovery)
- Dependency resolution
- Transport transformations

### Authentication
Most gateways perform some sort of authentication for **each request** (or series of requests). According to **rules** that are specific to each service, the gateway either routes the request to the requested microservice(s) or returns an error code (or less information). Most gateways add authentication information to the request when passing it to the microservice behind them. This allows microservices to implement **user specific logic** whenever required.

### Security
Many gateways function as a single entry point for a public API. In such cases, the **gateways handle transport security** and then dispatch the requests either by using a different secure channel or by removing security constraints that are not necessary inside the internal network. For instance, for a RESTful HTTP API, a gateway may perform **"SSL termination"**: a secure SSL connection is established between the clients and the gateway, and proxied requests are then sent over non-SSL connections to internal services.

<include src="TweetQuote" quoteText="Many gateways function as a single entry point for a public API."/>

### Load-balancing
Under high-load scenarios, gateways can **distribute requests among microservice-instances** according to custom logic. Each service may have specific scaling limitations. Gateways are designed to balance the load by taking these limitations into account. For instance, some services may scale by having multiple instances running under different internal endpoints. Gateways can dispatch requests to these endpoints (or even request the dynamic instantiation of more endpoints) to handle load.

### Request-dispatching
Even under normal-load scenarios, gateways can provide custom logic for dispatching requests. In big architectures, **internal endpoints are added and removed** as teams work or new microservice instances are spawned (due to topology changes, for instance). Gateways may work in tandem with service registration/discovery processes or databases that describe how to dispatch each request. This provides exceptional **flexibility** to development teams. Additionally, **faulty services** can be routed to backup or generic services that allow the request to complete rather than fail completely.

### Dependency resolution
As microservices deal with very specific concerns, some microservice-based architectures tend to become "chatty": to perform useful work, many requests need to be sent to many different services. For convenience and performance reasons, gateways may provide **facades** ("virtual" endpoints) that internally are **routed to many different microservices**.

### Transport transformations
As we learnt in the first post of this series, microservices are usually developed in isolation and development teams have great flexibility in choosing the development platform. This may result in microservices that return data and use transports that are **not convenient for clients** on the other side of the gateway. The gateway must perform the necessary **transformations** so that clients can still communicate with the microservices behind it.

## An API gateway example
Our example is a simple node.js gateway. It handles HTTP requests and forwards them to the appropriate internal endpoints (performing the necessary transformations in transit). It handles the following concerns:

### Authentication
Authentication using **JWT**. A single endpoint handles initial authentication: /login. User details are stored in a Mongo database and access to endpoints is restricted by roles.

```javascript
/*
 * Simple login: returns a JWT if login data is valid.
 */
function doLogin(req, res) {
    getData(req).then(function(data) {
        try {
            var loginData = JSON.parse(data);
            User.findOne({ username: loginData.username }, function(err, user) {
                if(err) {
                    logger.error(err);
                    send401(res);
                    return;
                }

                if(user.password === loginData.password) {
                    var token = jwt.sign({
                        jti: uuid.v4(),
                        roles: user.roles
                    }, secretKey, {
                        subject: user.username,
                        issuer: issuerStr
                    });

                    res.writeHeader(200, {
                        'Content-Length': token.length,
                        'Content-Type': "text/plain"
                    });
                    res.write(token);
                    res.end();                
                } else {
                    send401(res);
                }
            }, 'users');
        } catch(err) {
            logger.error(err);            
            send401(res);
        }
    }, function(err) {
        logger.error(err);            
        send401(res);
    });
}

/*
 * Authentication validation using JWT. Strategy: find existing user.
 */
function validateAuth(data, callback) {
    if(!data) {
        callback(null);
        return;
    }

    data = data.split(" ");
    if(data[0] !== "Bearer" || !data[1]) {
        callback(null);
        return;
    }

    var token = data[1];    
    try {
        var payload = jwt.verify(token, secretKey);
        //Your custom validation logic goes here.
        if(!payload.jti || revokedTokens[payload.jti]) {
            logger.debug('Revoked token, access denied: ' + payload.jti);
            callback(null);
        } else {        
            callback({jwt: payload});                
        }
    } catch(err) {
        logger.error(err);
        callback(null);
    }
}
```

> Disclaimer: the code shown in this post is not production ready. It is used just to show concepts. Don't copy paste it blindly :)

### Transport security
Transport security is handled through **TLS**: all public requests are received first by a reverse nginx proxy setup with sample certificates.

### Load balancing
Load-balancing is handled by **nginx**. See the sample [config](https://github.com/sebadoom/auth0/blob/master/microservices/gateway/nginx.conf).

### Dynamic dispatching, data aggregation and failures
Requests are **dynamically dispatched** according to a configuration stored in a database. Two types of requests are supported: HTTP and AMQP.

Requests also support the **aggregation strategy** for splitting requests among several microservices: a single public endpoint may aggregate data from many different internal endpoints (microservices). All returned data is in JSON format. See this excellent [post by Netflix](http://techblog.netflix.com/2013/01/optimizing-netflix-api.html) on how this strategy helped them achieve better performance. Also check our [post on Falcor](https://auth0.com/blog/2015/08/28/getting-started-with-falcor/) which allows for easy data fetching from many sources.

![Aggregation strategy](https://images.ctfassets.net/23aumh6u8s0i/5czB8vNeCDzOlE0SO9SYif/83a87ab75bd2bbe0a9a7d353ef33613d/aggregation)

**Failed internal requests** are handled by logging the error and returning less information than requested.

```javascript
/*
 * Parses the request and dispatches multiple concurrent requests to each
 * internal endpoint. Results are aggregated and returned.
 */
function serviceDispatch(req, res) {
    var parsedUrl = url.parse(req.url);

    Service.findOne({ url: parsedUrl.pathname }, function(err, service) {
        if(err) {
            logger.error(err);
            send500(res);
            return;
        }

        var authorized = roleCheck(req.context.authPayload.jwt, service);
        if(!authorized) {
            send401(res);
            return;
        }       

        // Fanout all requests to all related endpoints.
        // Results are aggregated (more complex strategies are possible).
        var promises = [];
        service.endpoints.forEach(function(endpoint) {   
            logger.debug(sprintf('Dispatching request from public endpoint ' +
                '%s to internal endpoint %s (%s)',
                req.url, endpoint.url, endpoint.type));

            switch(endpoint.type) {
                case 'http-get':
                case 'http-post':
                    promises.push(httpPromise(req, endpoint.url,
                        endpoint.type === 'http-get'));
                    break;
                case 'amqp':
                    promises.push(amqpPromise(req, endpoint.url));
                    break;
                default:
                    logger.error('Unknown endpoint type: ' + endpoint.type);
            }            
        });

        //Aggregation strategy for multiple endpoints.
        Q.allSettled(promises).then(function(results) {
            var responseData = {};

            results.forEach(function(result) {
                if(result.state === 'fulfilled') {
                    responseData = _.extend(responseData, result.value);
                } else {
                    logger.error(result.reason.message);
                }
            });

            res.setHeader('Content-Type', 'application/json');
            res.end(JSON.stringify(responseData));
        });
    }, 'services');
}
```

### Role checks
```javascript
var User = userDb.model('User', new mongoose.Schema ({
    username: String,
    password: String,
    roles: [ String ]
}));

var Service = servicesDb.model('Service', new mongoose.Schema ({
    name: String,
    url: String,
    endpoints: [ new mongoose.Schema({
        type: String,
        url: String
    }) ],
    authorizedRoles: [ String ]
}));

function roleCheck(jwt_, service) {
    var intersection = _.intersection(jwt_.roles, service.authorizedRoles);
    return intersection.length === service.authorizedRoles.length;
}
```

### Transport and data transformations
**Transport transformations** are performed to convert between HTTP and AMQP requests.

### Logging
**Logging** is centralized: all logs are published to the console and to an internal message-bus. Other services listening on the message-bus can take action according to these logs.

Get the full [code](https://github.com/sebadoom/auth0/tree/master/microservices/gateway).

## Aside: How webtask and Auth0 implement these patterns?

We told you about [webtasks](https://webtask.io) in our first post in the series. As webtasks *are* microservices they too run behind a gateway. The webtasks gateway handles authentication, dynamic-dispatching and centralized logging so that you don't have too.

* For authentication, [Auth0](https://auth0.com) is the issuer of tokens and webtask will verify those tokens. There is a trust relationship between them so that tokens can be verified.
* For real time logging webtask implemented a stateless resilient [ZeroMQ architecture](http://tomasz.janczuk.org/2015/09/from-kafka-to-zeromq-for-log-aggregation.html) which works across the cluster.
* For dynamic-dispatching, there is a custom-built Node.js proxy which uses [CoreOS etcd](https://github.com/coreos/etcd) as a pub-sub mechanism to route webtasks accordingly.

![Webtask](https://images.ctfassets.net/23aumh6u8s0i/26xA1D0RD9OZNmwuVPCCFw/6395ac83c869db331a701848bfa0e59f/webtask)

## Conclusion
API gateways are an essential part of any microservice-based architecture. Cross-cutting concerns such as authentication, load balancing, dependency resolution, data transformations and dynamic request dispatching can be handled in a convenient and generic way. Microservices can then focus on their specific tasks without code-duplication. This results in easier and faster development of each microservice.


"api gateway"