Most of our systems at Issuu are built as small services. Many of these services are meant to be serving frontend API calls and as such, have to expose HTTP endpoints to the outside world. But how do you account for routing between multiple services, load balancing and authentication? If only there was a piece of technology we had that could solve that problem already.

What's that? Oh, right! We already have a solution to this problem when it comes to backend-to-backend calls! All we needed to do is develop a smart API gateway that could somehow bridge HTTP and AMQP. And that's exactly we did.

Recently we looked at it and thought, why keep it only internally? Perhaps it can also help others out there solve their problems? And so, broen was open sourced.

What is broen?

Broen is an API gateway based on the AMQP broker. It leverages the broker for the majority of its functionality making it a very simple, yet powerful, piece of software.

In short, broen transforms HTTP requests into AMQP messages, that are then routed to various internal services using a simple routing algorithm. This gives us a range of benefits:

  • Load balancing is as simple as attaching multiple services to the same queue
  • Endpoints can be created and torn down very quickly
  • Routing is handled entirely by the AMQP broker
  • Authentication of requests can be performed in one central place
  • Spikes in traffic are handled easily thanks to the queue system of AMQP
  • Excellent horizontal scaling as new services being added simply mean new queues on AMQP

We have been using broen (internally known as the Thin Layer) for years at Issuu without any hitches or issues making our lives much easier in the process.

How does it work?

The diagram below shows the flow of HTTP requests through a system with broen.

Broen diagram

Authentication

The first step for any requests is its authentication. broen is fully customizable and allows you to define your own authentication plugin. That plugin will receive each requests and is meant to return data representing the result of the authentication. This data is fully opaque and will be attached to requests as seen later so it is fully up to you to define what it should be.

In our case, we forward the requests to a separate authentication service that, based off the data in your requests (e.g. cookies), returns information on the user that has sent the request.

Serialization

Once the request has gone through the authentication, it is then passed into the serializer plugin. Again, broen is fully customizable in that regard, and you can define your own favourite serialization protocol. Do you like JSON? Google Protobuf? Or maybe the esoteric msgpack? We do not impose any choice, although we do provide a sample JSON serializer.

Routing

The serialized request is then routed to your microservice. The routing is based off the URL of the requests which is neatly converted into an AMQP routing key. The endpoint root of broen is called /call and it also defines its own AMQP topic exchange on the broker called the http_exchange.

As such if you make a requests to, say, https://my-great-site.example.com/call/some-service/give-me-data the request will be routed to the http_exchange with the routing key of some-service.give-me-data. The message will contain all the parameters of the HTTP requests, so also the HTTP method and any query parameters it might have.

Such routing gives you a lot of flexibility in defining which service should handle which endpoints. Using routing wildcards such as * and # you can define it in any way you want.

Responses

Your service will receive the AMQP requests and process it. Once it's done it should return a response. Again, your serialization plugin determines what that will look like. Sending the response is as simple as responding to an AMQP RPC call. When broen gets your reply, it will deserialize it and turn it into an HTTP response back to the client. That's it!

Want more?

First of all, you can just head of to GitHub and grab broen! The README describes all you need to do to set it up yourself and give it a try. A sample client can be found here. All you need it a running RabbitMQ and these two to begin hacking.

You can also check out this talk from Code BEAM STO 2018, which includes a live demonstration on what it can do.

Don't be shy about letting us know what you think. Give us a ⭐️ if you like it or submit an issue if you'd like to see some changes!

Broen Joke