Building Apps and Services with the Hapi.js Framework

Hapi.js is described as “a rich framework for building applications and services”. Hapi’s smart defaults make it a breeze to create JSON APIs, and its modular design and plugin system allow you to easily extend or modify its behavior.

The recent release of version 17.0 has fully embraced async and await, so you’ll be writing code that appears synchronous but is non-blocking and avoids callback hell. Win-win.

The Project

In this article, we’ll be building the following API for a typical blog from scratch:

# RESTful actions for fetching, creating, updating and deleting articles
GET    /articles                articles#index
GET    /articles/:id            articles#show
POST   /articles                articles#create
PUT    /articles/:id            articles#update
DELETE /articles/:id            articles#destroy

# Nested routes for creating and deleting comments
POST   /articles/:id/comments   comments#create
DELETE /articles/:id/comments   comments#destroy

# Authentication with JSON Web Tokens (JWT)
POST   /authentications         authentications#create

The article will cover:

• Hapi’s core API: routing, request and response
• models and persistence in a relational database
• routes and actions for Articles and Comments
• testing a REST API with HTTPie
• authentication with JWT and securing routes
• validation
• an HTML View and Layout for the root route /.

The Starting Point

Make sure you’ve got a recent version of Node.js installed; node -v should return 8.9.0 or higher.

Download the starting code from here with git:

git clone https://github.com/markbrown4/hapi-api.git
cd hapi-api
npm install

Open up package.json and you’ll see that the “start” script runs server.js with nodemon. This will take care of restarting the server for us when we change a file.

Run npm start and open http://localhost:3000/:

[{ "so": "hapi!" }]

Let’s look at the source:

// server.js
const Hapi = require('hapi')

// Configure the server instance
const server = Hapi.server({
  host: 'localhost',
  port: 3000
})

// Add routes
server.route({
  method: 'GET',
  path: '/',
  handler: () => {
    return [{ so: 'hapi!' }]
  }
})

// Go!
server.start().then(() => {
  console.log('Server running at:', server.info.uri)
}).catch(err => {
  console.log(err)
  process.exit(1)
})

The Route Handler

The route handler is the most interesting part of this code. Replace it with the code below, comment out the return lines one by one, and test the response in your browser.

server.route({
  method: 'GET',
  path: '/',
  handler: () => {
    // return [{ so: 'hapi!' }]
    return 123
    return `<h1><marquee>HTML <em>rules!</em></marquee></h1>`
    return null
    return new Error('Boom')
    return Promise.resolve({ whoa: true })
    return require('fs').createReadStream('index.html')
  }
})

To send a response, you simply return a value and Hapi will send the appropriate body and headers.

• An Object will respond with stringified JSON and Content-Type: application/json
• String values will be Content-Type: text/html
• You can also return a Promise or Stream.

The handler function is often made async for cleaner control flow with Promises:

server.route({
  method: 'GET',
  path: '/',
  handler: async () => {
    let html = await Promise.resolve(`<h1>Google<h1>`)
    html = html.replace('Google', 'Hapi')

    return html
  }
})

It’s not always cleaner with async though. Sometimes returning a Promise is simpler:

handler: () => {
  return Promise.resolve(`<h1>Google<h1>`)
    .then(html => html.replace('Google', 'Hapi'))
}

We’ll see better examples of how async helps us out when we start interacting with the database.

The Model Layer

Like the popular Express.js framework, Hapi is a minimal framework that doesn’t provide any recommendations for the Model layer or persistence. You can choose any database and ORM that you’d like, or none — it’s up to you. We’ll be using SQLite and the Sequelize ORM in this tutorial to provide a clean API for interacting with the database.

SQLite comes pre-installed on macOS and most Linux distributions. You can check if it’s installed with sqlite -v. If not, you can find installation instructions at the SQLite website.

Sequelize works with many popular relational databases like Postgres or MySQL, so you’ll need to install both sequelize and the sqlite3 adapter:

npm install --save sequelize sqlite3

Let’s connect to our database and write our first table definition for articles:

// models.js
const path = require('path')
const Sequelize = require('sequelize')

// configure connection to db host, user, pass - not required for SQLite
const sequelize = new Sequelize(null, null, null, {
  dialect: 'sqlite',
  storage: path.join('tmp', 'db.sqlite') // SQLite persists its data directly to file
})

// Here we define our Article model with a title attribute of type string, and a body attribute of type text. By default, all tables get columns for id, createdAt, updatedAt as well.
const Article = sequelize.define('article', {
  title: Sequelize.STRING,
  body: Sequelize.TEXT
})

// Create table
Article.sync()

module.exports = {
  Article
}

Let’s test out our new model by importing it and replacing our route handler with the following:

// server.js
const { Article } = require('./models')

server.route({
  method: 'GET',
  path: '/',
  handler: () => {
    // try commenting these lines out one at a time
    return Article.findAll()
    return Article.create({ title: 'Welcome to my blog', body: 'The happiest place on earth' })
    return Article.findById(1)
    return Article.update({ title: 'Learning Hapi', body: `JSON API's a breeze.` }, { where: { id: 1 } })
    return Article.findAll()
    return Article.destroy({ where: { id: 1 } })
    return Article.findAll()
  }
})

If you’re familiar with SQL or other ORM’s, the Sequelize API should be self explanatory, It’s built with Promises so it works great with Hapi’s async handlers too.

Note: using Article.sync() to create the tables or Article.sync({ force: true }) to drop and create are fine for the purposes of this demo. If you’re wanting to use this in production you should check out sequelize-cli and write Migrations for any schema changes.

Our RESTful Actions

Let’s build the following routes:

GET     /articles        fetch all articles
GET     /articles/:id    fetch article by id
POST    /articles        create article with `{ title, body }` params
PUT     /articles/:id    update article with `{ title, body }` params
DELETE  /articles/:id    delete article by id

Add a new file, routes.js, to separate the server config from the application logic:

// routes.js
const { Article } = require('./models')

exports.configureRoutes = (server) => {
  // server.route accepts an object or an array
  return server.route([{
    method: 'GET',
    path: '/articles',
    handler: () => {
      return Article.findAll()
    }
  }, {
    method: 'GET',
    // The curly braces are how we define params (variable path segments in the URL)
    path: '/articles/{id}',
    handler: (request) => {
      return Article.findById(request.params.id)
    }
  }, {
    method: 'POST',
    path: '/articles',
    handler: (request) => {
      const article = Article.build(request.payload.article)

      return article.save()
    }
  }, {
    // method can be an array
    method: ['PUT', 'PATCH'],
    path: '/articles/{id}',
    handler: async (request) => {
      const article = await Article.findById(request.params.id)
      article.update(request.payload.article)

      return article.save()
    }
  }, {
    method: 'DELETE',
    path: '/articles/{id}',
    handler: async (request) => {
      const article = await Article.findById(request.params.id)

      return article.destroy()
    }
  }])
}

Import and configure our routes before we start the server:

// server.js
const Hapi = require('hapi')
const { configureRoutes } = require('./routes')

const server = Hapi.server({
  host: 'localhost',
  port: 3000
})

// This function will allow us to easily extend it later
const main = async () => {
  await configureRoutes(server)
  await server.start()

  return server
}

main().then(server => {
  console.log('Server running at:', server.info.uri)
}).catch(err => {
  console.log(err)
  process.exit(1)
})

Continue reading %Building Apps and Services with the Hapi.js Framework%

by Mark Brown via SitePoint