A rich framework for building restful API services. hapi is a configuration-centric framework in which authentication requirements, input validation, data caching and pre-fetching, developer documentation, and other essential facilities are provided out-of-the-box and enabled using simple JSON configuration objects. hapi enables developers to focus on writing reusable business logic instead of spending time with everything else.
For the latest updates and release information follow @hapijs on twitter.
Current version: 1.0.0 Release Candidate
Node version: 0.10 required
To demonstrate a basic example we will be creating a "hello world" service with a single API endpoint.
Start by creating a package.json by running
npm init
Now install hapi and have it saved to your package.json dependencies by running
npm install hapi --save
Next create an 'index.js' file and add the following contents to it:
var Hapi = require('hapi');
// Create a server with a host and port
var server = Hapi.createServer('localhost', 8000);
// Define the route
var hello = {
handler: function (request) {
request.reply({ greeting: 'hello world' });
}
};
// Add the route
server.route({
method: 'GET',
path: '/hello',
config: hello
});
// Start the server
server.start();Start the server with node . and navigate to the website at 'http://localhost:8000/hello' in a browser and you will see the following output:
{"greeting":"hello world"}To demonstrate one of the more powerful features in hapi we will change the 'hello' route to only respond whenever a 'name' is present on the querystring. Change the 'index.js' so that the 'hello' config object looks like the following:
var hello = {
handler: function (request) {
request.reply({ greeting: 'hello ' + request.query.name });
},
validate: {
query: {
name: Hapi.Types.String().required()
}
}
};When you start the server with node . and navigate to 'http://localhost:8000/hello' you will get a 400 response with an error explaining that 'name' is required. When the 'name' is omitted from the querystring the handler will not be called. However, if you do provide a 'name' it will be echoed out in the response. If you request 'http://localhost:8000/hello?name=John' then you will get the following response:
{"greeting":"hello John"}To learn more about the various validation options you can read the validation section in the reference.
The hapi route handler can be used to easily serve files, directories, render templates, and even proxy requests. In this example the 'directory' handler will be used to create a static site serving files in the 'public' folder. Remove the hello variable and make the server.route command look like the following:
server.route({
method: 'GET',
path: '/{path*}',
handler: {
directory: { path: './public', listing: false, index: true }
}
});Create a folder named 'public' and add a 'index.html' file in the folder with the following contents:
<html>
<head><title>Hello Static</title></head>
<body>
Hello Static
</body>
</html>Now when you request 'http://localhost:8000' you will see the html page rendered. You can add other files in this folder and they will be served. This is a good solution for serving static assets like images and css files.
To demonstrate how to use hapi to render templates we will be creating a template and rendering it using the handlebars engine. Begin by installing handlebars by running the following npm command:
npm install handlebarsNext create a directory named 'templates' that will contain the template files. In this directory create a 'index.html' with the following contents:
<html>
<head><title>{{greeting}}</title></head>
<body>
{{greeting}}
</body>
</html>The next step is going to be to tell the hapi server to use templates and the handlebars engine. After this, the route handler will be updated to render the template using an object that contains a 'greeting' property we want displayed. Change the 'index.js' file so that it looks like the following:
var Hapi = require('hapi');
var options = {
views: {
path: './templates',
engine: {
module: 'handlebars'
}
}
};
// Create a server with a host, port, and options
var server = Hapi.createServer('localhost', 8000, options);
// Define the route
var hello = {
handler: function (request) {
// Render the view with the custom greeting
request.reply.view('index.html', { greeting: 'hello world' }).send();
}
};
// Add the route
server.route({
method: 'GET',
path: '/',
config: hello
});
// Start the server
server.start();When you run the server with node . and view the homepage you will see the custom greeting message rendered. More information on using templates with hapi can be found in the views section of the API Reference.
For discussion about hapi join the #hapi channel on irc.freenode.net.