Kansas

Usage limited API to go!

Kansas will take care of the API usage accounting for you. It will track your API's usage using tokens with usage limits based on monthly fixed periods. You define policies, create tokens and consume them. Kansas uses Redis and works out of the box.

Read the full documentation

If you plan on using Kansas with Express then you need to check out the kansas-express package.

Installation

Install the module from npm

npm install kansas --save

var kansas = require('kansas');
 
var api = kansas();

Getting Started

There are three parts you need to understand and you are ready to get started with Kansas.

• Policies
• Token Creation and Consumption
• Maintenance

Policies

Policies are your plans. You can create as many as you wish and you will use them when creating tokens. Each policy defines the following properties:

• Name The policy name, i.e. "free", "basic", "advanced", "ultimate".
• Max Tokens The maximum number of tokens an owner can create.
• Limit The maximum number of API calls (units) per period.
• Period The time period, for now it's fixed to Monthly, there's the ability to have daily periods too, maybe in a later version.

Policies are stored in memory. After many iterations it became apparent that this is the most convenient way to work with policies. You define and maintain them inside your application, they are shared between multiple cores and exist in the memory saving on needless database reads. After all, typically an application is not expected to have more than 10 policies.

Token Creation and Consumption

That's pretty straightforward, you create tokens and consume them. Each token requires an ownerId and a policyName. The ownerId can be any string that identifies the owning entity of the token, a user, a company, anything. The policyName must match a previously created policy.

Each token creation will create a set of key/value pairs of various types for various reasons, i.e. indexing. Kansas will properly clean up all created keys when a token is deleted and will do so atomically.

From the keys created, the ones you should care about are the Usage type of keys. Kansas will create the current and next period's usage keys with every token created. Which means that for every new month an operation needs to run to populate the usage keys for the next month. This brings us to the next part, maintenance.

Maintenance

As described above, on each new month you need to populate the usage keys for the next month. Kansas didn't want to take any initiatives with that as depending on how many tokens you have registered it can be an expensive operation.

So Kansas will kindly offer you a method to run yourselves so it can properly populate next month's usage keys.

These are the main concepts you need to understand, now you are ready to dive into the API!

Read the full documentation

Release History

• v0.3.8, 03 Feb 2016
  • Fixed an issue with changing policy.
  • Updated all packages to latest.
• v0.3.7, 03 Aug 2015
  • Prepopulation will now check current period's usage keys if exist and if not create them, it will also not overwrite future keys if they are found.
• v0.3.6, 03 Apr 2015
  • Fixed Redis version check issue, thanks @sirodoht.
• v0.3.5, 03 Mar 2015
  • Added more debug logging on get usage.
• v0.3.2, 19 Oct 2014
  • Fixed a bug in Initdb, not properly initializing the database name.
• v0.3.1, 19 Oct 2014
  • Properly exposed testing Initdb, moved out of npm-ignored test/ folder.
• v0.3.0, 18 Oct 2014
  • Fixed spelling mistake in db nuking confirmation string.
• v0.2.5, 13 Oct 2014
  • Refactored and exposed the internal Initdb Constructor for nuking and populating a test database.
  • Upgraded all dependent packages to latest.
• v0.2.4, 07 Aug 2014
  • Added the kansas.getUsage() and kansas.getUsageByOwnerId() methods.
• v0.2.3, 15 Jun 2014
  • Fix deleting non existing key bug.
• v0.2.2, 04 Apr 2014
  • Created the Count Policy Type.
  • Optimizations in consume methods.
• v0.1.16, 29 Feb 2014
  • Update all dependencies to latest.
  • More defense on db prepopulation for corrupt records.
• v0.1.12, 11 Feb 2014
  • Upgraded to logg 0.3.0, enables multi-package logger instances.
• v0.1.11, 09 Feb 2014
  • Better error message on Redis version incompatibility.
• v0.1.10, 09 Feb 2014
  • Fix policy period to month.
  • Allow for creation of custom tokens.
  • Will now check if token exists before creating it.
• v0.1.8, 08 Feb 2014
  • Improve Logging piping.
• v0.1.7, 03 Mar 2014
  • Master switch for logging on testing.
  • Optimize prepopulation method, fix context bug, add more debug logging.
  • Introduce logger unmute and addConsole.
  • Expose "removeListener" method.
  • Export logger.
• v0.1.6, 03 Mar 2014
  • Better conditional for determining usage of DECR vs DECRBY
• v0.1.5, 02 Mar 2014
  • Fix bug with prepopulate.
• v0.1.4, 02 Mar 2014
  • Upgrade all packages to latest.
• v0.1.3, 02 Mar 2014
  • Better connection management to redis
  • Protect against older versions or Redis that wont work with Kansas (require 2.8.x+)
• v0.1.2, 02 Mar 2014
  • More defence on prepopulate method.
• v0.1.0, 02 Mar 2014
  • Big Bang

License

Copyright (c) 2014 Thanasis Polychronakis. Licensed under the MIT license.