Realtime API management with Pushpin and Kong

Pushpin is the open source reverse proxy for the realtime web. One of the benefits of Pushpin functioning as a proxy is that it can be combined with an API management system, such as Mashape’s Kong. Kong is the open source management layer for APIs. To use Kong with Pushpin, simply chain the two together on the same network path.

Why would you want to use an API management system with Pushpin? Realtime web services have many of the same concerns as request/response web services, and it can be helpful to centrally manage those aspects.

For example, Kong enables centralized management of concerns such as:

• Authentication
• Logging/analytics
• Traffic manipulation

See Kong’s plugin page for a full list of features.

Proxy order

Since both Pushpin and Kong are reverse proxies, you may wonder what order they should be placed. As it turns out, both ways work, with different trade-offs.

If Pushpin is placed in front of Kong:

• Kong is able to inspect/manipulate any instructions the backend sends to Pushpin.
• Pushpin can convert WebSocket connections into a series of HTTP requests, allowing Kong to manage a WebSocket API.
• Kong is unable to see data published through Pushpin.

If Kong is placed in front of Pushpin:

• Kong sees data published through Pushpin.
• WebSockets won’t work.
• Kong logging of HTTP streaming will delay until connection closes.

If you’re using the Fanout Cloud version of Pushpin, then you don’t have much choice; it’ll always come first. Fortunately, this is arguably the preferred order. However, if you are running Pushpin and Kong on your own servers, then you can choose either order.

Authentication

API consumer authentication is one of the most valuable features of Kong. It can be used to provide protection to an API without having to implement authentication in the backend.

Suppose we have an HTTP streaming endpoint with the following architecture:

• Pushpin listening on port 80, forwarding requests to localhost port 8000 (Kong).
• Kong listening on port 8000, forwarding requests for api.example.com to port 9000 (internal API backend).
• API backend listening on port 9000, serving a Pushpin-based HTTP streaming endpoint “/events/”, with no built-in authentication.
• Kong also listening on port 8001, to handle internal management API calls.

With this architecture in place, a client is able to make a request to http://api.example.com/events/ and establish a long-lived HTTP streaming response:

$ curl -i http://api.example.com/events/

HTTP/1.1 200 OK
Via: kong/0.3.2
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: Transfer-Encoding

{ ... event ... }
{ ... event ... }
...

We can then protect this API using Kong’s keyauth plugin. Below is a sequence diagram of how the network flow will work:

To set up Kong authentication, the first thing we do is add the keyauth plugin to the configured API:

$ curl -i -d name=keyauth -d value.key_names=Auth-Key \
  http://localhost:8001/apis/{api-id}/plugins

What this will do is block all requests to the API that do not provide a valid Auth-Key header. For example, here’s what happens if we access the API right now without a key:

$ curl -i http://api.example.com/events/

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Server: kong/0.3.2
Content-Length: 49
 
{"message":"Invalid authentication credentials"}

Next we’ll create a consumer object and API key within Kong to be used for authentication. First we create the consumer:

$ curl -d username=alice http://localhost:8001/consumers/

Then we create an API key for that consumer:

$ curl -d key=supersecret \
  http://localhost:8001/consumers/{consumer-id}/keyauth

Now the streaming endpoint becomes accessible again using the API key:

$ curl -i -H "Auth-Key: supersecret" http://api.example.com/events/

HTTP/1.1 200 OK
Via: kong/0.3.2
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: Transfer-Encoding

{ ... event ... }
{ ... event ... }
...

Adding authentication to a realtime API doesn’t get easier than this!

WebSockets

Pushpin is able to convert WebSocket connections into a series of HTTP requests. This allows backend services (e.g. a service built with django-grip) to drive WebSocket connections without needing direct support for WebSockets. With this mode enabled, Kong is able to proxy the converted HTTP traffic between Pushpin and the backend.

This means you can use Kong to protect a WebSocket API the same way you would a normal HTTP API. Below is another sequence diagram, this time for a network flow involving WebSockets:

Suppose you have a WebSocket API living at ws://api.example.com/events/ that you can normally access like this:

$ wscat -c ws://api.example.com/events/
connected (press CTRL+C to quit)

If the keyauth Kong plugin is enabled, then accessing this API will require a key. For example, here’s a connection attempt made without a key:

$ wscat -c ws://api.example.com/events/
error: Error: unexpected server response (403)

As you can see, a 403 error is received, just like with HTTP. Access will only be granted if a valid key is provided:

$ wscat -H "Auth-Key: supersecret" -c ws://api.example.com/events/
connected (press CTRL+C to quit)

Additionally, WebSocket events will show up in Kong’s logs as HTTP requests, which can be used for traffic analysis.

Logging

Logging is another useful function of Kong. It can be used to track traffic for analytics or billing purposes. To enable logging to a remote TCP server, add the tcplog plugin like this:

$ curl -i -d name=tcplog -d value.host=localhost -d value.port=9999 \
  http://localhost:8001/apis/{api-id}/plugins

With the tcplog plugin added to the API, any requests, including those that become HTTP streaming connections or get converted into WebSocket events, will be logged along with information about the authenticated consumer.

Conclusion

All APIs can benefit from API management, realtime or not. Pushpin makes it easy to create realtime APIs that can be managed by API management systems. If you are designing or building a realtime API infrastructure, definitely check out Pushpin and Kong. They are a great pair.