api-cli

Framework to build CLI-based applications and helper scripts

ApiCli - A framework for CLI-based applications based on Node.JS

I simply love Node.JS to create lean, CLI-based applications to access APIs in order to automate tasks. In order to speed up the development process, I created this library as a blueprint/framework.

For example I used api-cli to implement a CLI to connect to the Lingulog API. This is how an example call would look like:

lingulog projects list -sort=name

Simply install via NPM

npm install api-cli

For each API, I first create a simple API definition file, which is usually called api.json. This file contains all API classes as well as their respective methods.

{
  "version": "1.0.0",
  "url": "http://...",
  "data": {
    "tasks": [
      {
        "cmd": "import",
        "method": "post",
        "route": "/",
        "description": "Import tasks",
        "param": [],
        "return": {
          "type": "array",
          "description": "List of activites [{Id, Date, Entity, Index, Meta, Type}, ...]"
        }
      },
      {
        "cmd": "export",
        "method": "get",
        "route": "/",
        "description": "Export tasks",
        "param": [
          {
            "name": "assigneduser",
            "type": "string",
            "description": "The assigend user",
            "optional": true
          },
          {
            "name": "index",
            "type": "int",
            "description": "The object ID",
            "optional": true
          },
          {
            "name": "filter",
            "type": "array",
            "description": "A filter array {search, orderby, orderasc}",
            "optional": true
          },
          {
            "name": "output",
            "type": "string",
            "description": "Output file name",
            "optional": true
          }
        ],
        "return": {
          "type": "array",
          "description": "List of activites [{Id, Date, Entity, Index, Meta, Type}, ...]"
        }
      }
    ]
  }
}
 

To create a new app, you first have to include the ApiCli class:

var ApiCli = require('api-cli');

After that, you can load the API definition from your JSON file. (But if you don't want to add an extra file, if of course OK to simple define the API definition object right in your code):

var apidoc = JSON.parse(
    fs.readFileSync(path.join(path.dirname(fs.realpathSync(__filename)), '..', 'lib', 'api.json'))
);

After that, you create a new class instance, where you can specify your properties and methods.

var app = new ApiCli({

Finally, you can invoce the run method in order to execute your application:

app.run();

A complete example would look like this:

var path   = require('path');
var fs     = require('fs');
var ApiCli = require('api-cli');
 
var apidoc = JSON.parse(
    fs.readFileSync(path.join(path.dirname(fs.realpathSync(__filename)), '..', 'lib', 'api.json'))
);
 
var app = new ApiCli({
    AppName      : 'api-cli Client',         // {string} Application name 
    AppBin       : 'api-cli',                // {string} Application executable 
    AppVersion   : '1.0.0',                  // {string} The required API version 
 
    ApiDoc       : apidoc,                   // {object} The API definition object 
    ApiName      : 'tasks',                  // {string} The API name (e.g. project, user, etc.) 
    ApiTask      : null,                     // {string} The API task 
    ApiParams    : null,                     // {array}  Additional CLI parameters 
    ApiDefinition: null,                     // {object} API definition 
 
    CliParams: [                             // {array}  Default CLI options and short hands 
        {
            'name': 'help',
            'type': 'boolean',
            'description': 'Show help'
        },
        {
            'name': 'config',
            'type': 'string',
            'description': 'Configuration file'
        },
        {
            'name': 'username',
            'type': 'string',
            'description': 'User name',
            'input': 'text'
        },
        {
            'name': 'password',
            'type': 'string',
            'description': 'User password',
            'input': 'hidden'
        }
    ],
    CliShortcuts: {
        'c': ['--config'],
        'h': ['--help'],
        'f': ['--file']
    },
    evalResponsefunction(errresponsebody) {
        if (err) throw err;
 
        console.log('Do something with the API result...', body);
    }
});
app.run();

The ApiCli class has various properties and classes, with those marked public can be specified upon initialization (see sample above).

ParameterTypePublicDescription
AppNamestringYesThe name of the applicaiton
AppBinstringYesThe filename for the binary executable
AppVersionstringYesThe app version
ApiDocobjectYesThe API documentation object
ApiNamestring/nullYesThe name of the API (default: null)
ApiDefinitionobjectNoContains the API definition object, after initialization
CliParamsobjectYesSpecifies the default CLI parameters
CliShortcutsobjectYesSpecifies shortscut parameters
CliOptionsobjectNoContains the user's CLI input options
evalResponsefunctionYesFunction called to evaluate the HTTP response
executefunctionYesFunction called after initialization to execute the API task

The execute function by default simply referrs to the _

Node.js with NPM (Tested with Node Version 0.10.22)

This work is licensed under the GNU Lesser General Public License (LGPL). You may also get a copy of the GNU Lesser General Public License from http://www.gnu.org/licenses/lgpl.txt.