This post is adapted from Modulus’ excellent introduction to HAPI.
I might have mentioned Livewire around here a couple of times. Livewire is my little (and getting littler) HTTP router with a functional bent, for Node.js. Since 0.5, released this weekend, it’s been based on Highland, a high-level streams library.
You’ll need Node.js 0.10, which comes bundled with npm. Create a
package.json, which you can do by hand or with
npm init. We’ll install a few things:
- Livewire is why we’re here
- Oban is a streaming adaptor for Node.js’ HTTP servers
- Dram is an expressive response creator for Oban
A simple server
require Oban and http and create a server:
This doesn’t actually do anything on its own. Add a function to handle the request, and send a response, using a Livewire router:
That’s the complete server. Notice that it’s all code, not configuration. Start it up, and
Basic REST API
As per the HAPI post, we’ll build a simple API to retrieve and save quotes. Let’s start with a list of quotes, and a route to get them all.
Unlike HAPI, Livewire doesn’t guess content types or serialise objects, so we’re doing it manually. Dram’s chaining API lets us do this quite nicely; I’ve pulled out a function to format the responses, as we’ll be using it quite a bit.
Now, we’ll add a
/random route, which will return a random quote. Up till now, we’ve been using a single route at a time; for multiple routes, Livewire has the
route function, which takes an array of handler functions, and returns the first matching result. Modify your server like so:
While we’re here, we can add a fallback route, to handle any path the other routes can’t. Since a route is just a function returning a stream, we can add a function always returning a 404 response at the end of our
Up next is returning a single quote by its index. We add a URL parameter to a route; this is an identifier preceded by a colon, such as
NB from here on in, I’ll just be giving the routes; these should be added to the array, before the fallback.
Now, we’ll add a
POST route to add a quote to the array. I won’t be covering validation, mostly because there’s no Oban-compatible module to do it yet.
This nicely highlights Livewire’s way of dealing with asynchronous responses. Since reading the request body stream is asynchronous, we have a streaming body parser, which decodes the body and sends it as a stream containing a single object.
flatMap is just to transform the object stream into a response stream: notice we’re still doing
return json(...), even within the asynchronous call.
POST request, and we get the new quote back:
And it’s in the array now:
Finally, we’ll add quote deletion. This looks a lot like our single-quote route. We slice the quote ID out of the array, and simply return a
DELETE the quote we just added.
Thus concludes our whirlwind tour of Livewire. In fact, I’ve covered pretty much everything it does. Livewire and its sibling libraries are designed to be solid bases for more complex functionality. For an example, have a look at Sodor, which is a Controller-like interface to Livewire’s routes. In this very post, we’ve used a wrapper library: Dram is based on the more low-level Peat, which is the library Oban itself uses. With raw Peat, we’d be writing
[Status(200), "hello"] instead of
The code backing this tutorial is on Github. For inspiration, examples, and documentation, have a look at Livewire, Highland, Dram, Oban and Peat.