vapic

Versioned API Cache

Installation

npm install vapic --save

Usage

.set()

Stores the value in the cache, against the current version.

const vapic = require('vapic');

vapic.set({
	url: '/foo',
	value: 'bar'),
	maxVersions: 3, // (1)
	redisClient: require('redis').createClient(),
}, (err, result) => { /* ... */ });

1. If maxVersions is set, cullOld() is automatically called.

Options:

url

Used to construct the cache key

value

The value to store in the cache

maxVersions

The maximum number of cached versions to store; when set .cullOld() is called.

versionMatchType

How to determine which version to match.
When exact (the default), only an exact version match with the current version will be returned.
When skipWhenSameAsLatest, does not insert a new version if the value of the most recent version is the same as the new one you are inserting; use when multiple version are likely to contain the same value.

.cullOld()

Deletes older versions that have been cached. The versions to keep/ remove are determined using semver.

const vapic = require('vapic');

vapic.cullOld({
	url: '/foo',
	maxVersions: 3,
	redisClient: require('redis').createClient(),
}, (err, result) => { /* ... */ });

Options:

Same as .set().

express middleware

const vapic = require('vapic');
const express = require('express');

const vapicOptions = {
	permittedAge: 3600, // one hour
	cacheVersion: require('package.json').version,
	redisClient: require('redis').createClient(),
};

const router = express.Router();
router.get('/foo', vapic.expressMiddleware(vapicOptions), (req, res) => {
  if (req.vapicError) {
		res.status(404).json({
			message: 'Data unavailable',
		});
		return;
	} else {
  	const data = JSON.parse(req.vapicResult);
  	res.json(data);
  	return;
  }
});

module.exports = router;

Options:

prefix

Prefix for the cache key. Defaults to vapic:/

cacheVersion

Cached version to use. Defaults to the version number of the current module, or process.env.npm_package_version

versionMatchType

How to determine which version to match.
When exact (the default), only an exact version match with the current version will be returned.
When latestUpToCurrent, the latest version that is less than or equal to the current version will be returned.

readVersionFromHeader

If set to true, will read the contents of the vapic HTTP request header, and if the version property is present, it will use that instead of the specified cacheVersion.
This is most useful when there are multiple versions of clients being served by the same server, and each of them needs to lock down their expected responses to a particular version.
The vapic HTTP request header’s value is expected to be a base64 encoded JSON string, e.g. {version:'0.0.1'} ⇒ 'eyJ2ZXJzaW9uIjoiMC4wLjEifQ=='.

permittedAge

The number of seconds the Cache-Control header in the response should set its max-age to. Defaults to 60 (One minute).

logger

An object that has an error function. Defaults to console

redisClient

A Redis client instance. Defaults to require('redis').createClient().

💡	vapic.expressMiddleware() where versionMatchType=latestUpToCurrent is intended for use in conjunction with vapic.set() where versionMatchType=skipWhenSameAsLatest

💡	Convenience object to JSON conversion utilities are exposed in vapic.util. If you wish to import this without require-ing all of vapic, you can also require('vapic/util.js') directly.

Development

If you would like to contribute, fork the git repo, and create a branch off the develop branch, and submit your pull request when you are done.

ℹ️	This repo uses the git flow branching strategy.

To run tests:

npm run test

Author

Brendan Graetz

Licence

GPL-3.0