Hapi Web Service is a module built to help you conceive more standard Web Services with hapi. Whereas other modules will help you build REST-like interfaces for your application, HWS helps you build RPC-like services, allowing you to conceive your own methods while easily ensuring global QoS to your services - access protection, JSON output, error management and service description.
Run npm install --save hapi-web-service.
const hws = require('hapi-web-service')
const Joi = require('joi')
const users = [{
name: 'Johnny Appleseed'
}, {
name: 'Kim Minjun'
}, {
name: 'John Smith'
}]
// Creating a service
let userService = new hws.Service('users')
// Creating a method for this service
let getUsersNamesMethod = new hws.Method('getUsersNames',
// input validation object
Joi.object().keys({
name: Joi.string().alphanum()
}),
// output format
Joi.array().items(Joi.string().alphanum()),
// method handler
function (args, session, callback) {
if (args.name) {
callback(null, users.filter((user) => { return user.name.indexOf(args.name) !== -1 }).map((user) => { return user.name }))
} else {
callback(null, users.map((user) => { return user.name }))
}
}
)
// Registering the method to the service
userService.registerMethod(getUsersNameMethod)
// Adding the service to the server
userService.registerToServer(server)
// The service is now available at /users/getUsersNamesMethod.
Creates a service that will be accessible via /[name] where:
name- the name of the service in service description and the basis of endpoints in the URI.
Registers an interface into the server where:
method- ahws.Method().
Registers the service and its interfaces into the server, where:
server- aHapi.Server().
Creates an interface that will be accessible via /[service]/[name] where:
name- the name of the interface and part of the endpoint in the URI.input- a Joi object representing an object, of which the keys are input elements.output- a Joi object representing the output. This is added both for control and for description purposes.method- a function with the following parameters:function method(args, session, callback)where:args- a JavaScript object with the different inputs. It contains both the URI inputs (ex:?name=John&age=18), and the payload, for example in aPOSTrequest. The payload must be in a JSON format to be recognized. If an argument is present both in the URI and in the payload, the argument from the query is saved in theargsobject, and the payload argument is saved in theargsobject, but with a_payload_prefix to its key.session- a JavaScript object representing the session contentscallback- a function with the following parameters:function callback(err, data)where:err- an error. Iferris a Boom error, it takes into account its properties.data- a variable with the output data.
httpMethod- optional parameter, default toGET. A string with the HTTP method (POST,PUT...) to use the service.requiredAuth- optional parameter, default tohws.BasicAuthRequirement()(always accepting the request), allowing an access control to this interface. To create a custom access control, you can create your ownhws.BasicAuthRequirement()subclass (see API).
Object for controlling access to a route. Creating a subclass of hws.BasicAuthRequirement() allows you to create your own access control procedures.
Declares if the interface is accessible - in the default version, always accepts - where:
args- a JavaScript object with the different inputssession- a JavaScript object representing the session contentscallback- a function with the following parameters:function callback(err, grant)where:err- an errorgrant- ahws.Grant()object.
Object transmitted to the engine by the hws.BasicAuthRequirement() to signal if the access to the route has been granted, where:
type: is one of thehws.grantTypesvalues -hws.grantTypes.granted,hws.grantTypes.refusedorhws.grantTypes.notConnected. This value allows us to determine the HTTP status code to use in the answer.description: a string describing more in detail why the access has been forbidden.
Returns a boolean equal to true if access has been granted - returns false if access has been refused.
Returns a boolean equal to true if access has been refused because the user wasn't connected (inducing an error 401) - and false if this is because the user didn't have the rights.
const hws = require('hapi-web-service')
const Joi = require('joi')
const users = [{
name: 'Johnny Appleseed'
}, {
name: 'Kim Minjun'
}, {
name: 'John Smith'
}]
const accesses = {
iamasecretkey: 'none',
iamamoresecretkey: 'all'
}
// Creating a service
let userService = new hws.Service('users')
// Creating an authRequirement for a route allowing to get all the users
let getAuthRequirement = new hws.basicAuthRequirement()
getAuthRequirement.check = function (args, session, callback) {
if (args.key) {
if (accesses[args.key] === 'all') {
callback(null, new hws.Grant(hws.grantTypes.granted))
} else {
callback(null, new hws.Grant(hws.grantTypes.refused))
}
} else {
callback(null, new hws.Grant(hws.grantTypes.notConnected))
}
}
// Creating a method for this service
let getUsersNamesMethod = new hws.Method('getUsersNames',
// input validation object
Joi.object().keys({
name: Joi.string().alphanum()
}),
// output format
Joi.array().items(Joi.string().alphanum()),
// method handler
function (args, session, callback) {
if (args.name) {
callback(null, users.filter((user) => { return user.name.indexOf(args.name) !== -1 }).map((user) => { return user.name }))
} else {
callback(null, users.map((user) => { return user.name }))
}
},
// HTTP method
'GET',
// auth requirement
new getAuthRequirement()
)
// Registering the method to the service
userService.registerMethod(getUsersNameMethod)
// Adding the service to the server
userService.registerToServer(server)
// The service is now available at /users/getUsersNamesMethod and the route is controlled.
Feel free to contribute if you would like! Please read our current issues and pull request if you'd like to submit one. Our lint standard relies on JS Standard.
-
Completing the expected behaviour of the package
-
Adding custom method URI
-
Adding testing
-
Adding WDSL