Hapi API Versioning Plugin

Common errors

• Cannot read properties of undefined (reading 'register') or server.register is not a function

  cause Attempting to use a Hapi.js version incompatible with the plugin's API, or incorrect plugin registration syntax.
  fix Ensure you are using `@hapi/hapi` version `17.x.x` as a peer dependency, and that `server.register` is called with an object containing a `plugin` key set to the required module and an `options` key. Check Hapi's migration guide if moving between major versions.

• Error: Plugin options validation failed

  cause Missing or invalid required options during plugin registration, such as `validVersions`, `defaultVersion`, or `vendorName`.
  fix Provide all required options (`validVersions` as an array of integers, `defaultVersion` as an integer within `validVersions`, and `vendorName` as a string) during plugin registration. Refer to the plugin's documentation for option specifics.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: X)

  cause Hapi server startup or plugin registration failed silently due to an unhandled promise rejection, often related to port conflicts or other initialization errors.
  fix Wrap your `init` function call or the `server.start()` and `server.register()` calls in a `try...catch` block to properly log and handle errors during server initialization. Ensure the port is not already in use.

Warnings

• breaking This plugin is strictly compatible with Hapi.js versions 17.x.x. It is not maintained for or compatible with newer Hapi versions (e.g., v20, v21+), which have introduced significant breaking changes and ESM support.
  Fix: For modern Hapi.js (v20+), consider alternative API versioning strategies or a different plugin. Migrating to a newer Hapi version will require finding a new versioning solution or implementing custom logic.
• gotcha The plugin relies on `accept` headers (with `vendorName`) or a custom header (default `api-version`) to determine the requested API version. If neither is present, it defaults to the `defaultVersion` specified in the options. Clients must correctly provide one of these headers.
  Fix: Ensure client applications send either an `Accept` header in the format `application/vnd.<vendorName>.v<version>+json` or a custom header like `api-version: <version>`. For example, `Accept: application/vnd.mysuperapi.v1+json` or `Api-Version: 1`.
• gotcha The `hapi-api-version` plugin achieves versioning by internally rewriting requested URLs (e.g., `/users` to `/v1/users`). Developers defining versioned routes must ensure their route paths match this rewritten format (e.g., `/v1/users` and `/v2/users`) for the plugin to function correctly.
  Fix: When defining version-specific routes, structure your `path` options to include the version (e.g., `/v{version}/resource`). The plugin will then map the unversioned incoming request to the correct internal versioned path.
• deprecated The package `hapi-api-version` has not been updated in 7 years. Its last stable version (2.3.1) targets Hapi.js v17.x. This indicates the package is effectively abandoned and not maintained for contemporary Node.js or Hapi.js versions.
  Fix: Avoid using this package in new Hapi.js projects. For existing projects, consider migrating to a newer, actively maintained Hapi.js version and finding an alternative API versioning solution that is compatible with Hapi v20+ or v21+.

Install

• npm install hapi-api-version npm
• yarn add hapi-api-version yarn
• pnpm add hapi-api-version pnpm

Imports

• hapiApiVersion
  wrong:

  import hapiApiVersion from 'hapi-api-version';

  correct:

  const hapiApiVersion = require('hapi-api-version');

  This plugin is CJS-only and primarily intended for direct registration with a Hapi server. It does not export named members. Modern Hapi versions (v20+) support ESM, but this plugin does not.
• Plugin Registration
  wrong:

  await server.register(hapiApiVersion, { options: { validVersions: [1, 2] } });

  correct:

  await server.register({ plugin: require('hapi-api-version'), options: { validVersions: [1, 2], defaultVersion: 2, vendorName: 'mysuperapi' } });

  The plugin is registered as an object with a `plugin` key referencing the required module, and an `options` object for configuration.

Quickstart

This quickstart demonstrates setting up a Hapi server, registering the hapi-api-version plugin with basic options, and defining both versioned and unversioned routes. It shows how to access the detected API version from `request.pre.apiVersion` to serve different data based on the client's requested version.

'use strict';

const Hapi = require('@hapi/hapi');
const hapiApiVersion = require('hapi-api-version');

const init = async function () {
    try {
        const server = new Hapi.server({ port: 3000 });
        await server.register({
            plugin: hapiApiVersion,
            options: {
                validVersions: [1, 2],
                defaultVersion: 2,
                vendorName: 'mysuperapi'
            }
        })

        server.route({
            method: 'GET',
            path: '/users',
            handler: function (request, h) {
                const version = request.pre.apiVersion;
                if (version === 1) {
                    return [{ name: 'Peter Miller' }];
                }
                return [{ firtname: 'Peter', lastname: 'Miller' }];
            }
        });

        server.route({
            method: 'GET',
            path: '/loginStatus',
            handler: function (request, h) {
                return { loggedIn: true };
            }
        });

        await server.start();
        console.log('Server running at:', server.info.uri);
    }
    catch (err) {
        console.error('Server startup error:', err);
        process.exit(1);
    }
};

init();