README

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

Purpose

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.

Installation

Simply install via NPM

npm install api-cli

API Definition

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}, ...]"
        }
      }
    ]
  }
}

App Configuration

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']
    },
    evalResponse: function(err, response, body) {
        if (err) throw err;

        console.log('Do something with the API result...', body);
    }
});
app.run();

Methods and Properties

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

Parameter	Type	Public	Description
AppName	string	Yes	The name of the applicaiton
AppBin	string	Yes	The filename for the binary executable
AppVersion	string	Yes	The app version
ApiDoc	object	Yes	The API documentation object
ApiName	string/null	Yes	The name of the API (default: null)
ApiDefinition	object	No	Contains the API definition object, after initialization
CliParams	object	Yes	Specifies the default CLI parameters
CliShortcuts	object	Yes	Specifies shortscut parameters
CliOptions	object	No	Contains the user's CLI input options
evalResponse	function	Yes	Function called to evaluate the HTTP response
execute	function	Yes	Function called after initialization to execute the API task

The execute function by default simply referrs to the _

Requirements

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

request: ~2.27.0
nopt: ~2.1.2
read: ~1.0.5
cli-table: ~0.2.0
prettyjson: ~0.10.0

License

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.

Usage no npm install needed!