Server API Documentation

This is the Server API Documentation for Caesar.js secure microservices node framework.

Getting Started with the Server API Documentation

First of all install Caesar.js in your node project by running

npm install caesarjs --save

At this point you are ready to run the Caesar.js service.

Caesar.js Server API Documentation

Caesar.js server can be run in either HTTP and secure mutual certificate authentication modes. This section deals with running the server in HTTP mode. Remember that even in HTTP Mode the caesar.js server will be able to send and receive encrypted data to and from the server.

THE API Methods

Constructor ( port: integer, options: object)

The constructor takes 2 arguments in the following order:

  • Port (integer) – This is the port you would like to run the caesar.js server on
  • Options (Object) – For the HTTP mode server you only need an encryptor key string. This string must be at least 16 characters long.

The constructor is chainable and returns an instance of the server itself.

Example:

const server = require('caesarjs').server;
const encryptorKey = '33a24560-a43b-44cc-b2bc-9cc0de14a093';
new server(3000, {encryptorKey})

Constructor Options Object

The option object is made up of the following keys:

  • encryptorKey (required) – The encryptorKey is required and it should be the same one used by the client. This is used to encrypt/decrypt data sent to or from the client/server. It must be a string of at least 16 characters
  • maxNumberOfRequests (optional) – This sets the overall number of daily calls a client or clients are allowed to perform
  • key (optional) – This is the server’s private key needed to run the server securely in HTTPS protocol and to enable as well mutual certificate authentication with the client.
  • cert (optional) – This is the server’s CA Root signed certificate

Examples:

a) Running the server in HTTP protocol

const serverOptions = {
encryptorKey: encryptorKey
};

b) Running the server in HTTPS protocol with client mutual certificate authentication. To run the server this way you must provide either the keys and cert keys.

{
encryptorKey: encryptorKey,
key: fs.readFileSync(path.join(__dirname, 'path', 'to', 'privkey.pem')),
cert: fs.readFileSync(path.join(__dirname, 'path', 'to', 'fullchain.pem')),
}

c) Running the server with a maximum endpoint daily allowance set

const serverOptions = {
encryptorKey: encryptorKey,
maxNumberOfRequests: 1000
};

add( patternMatcher: object, expressCallBack: function )

The add method allows the user to create an endpoint and it takes 2 arguments in the following order:

  • Pattern matching object (Object) – This must be a flat object and should define the service you are building. The user’s client will locate the service by providing the specific pattern.
  • An Express route function (Function) – This takes 2 parameters as any other express route function being req and res

The add method is chainable and returns an instance of the caesar.js server.

Example:

new server(3000, {encryptorKey})
.add(
{role: 'calculator', operation: 'sum'}, // pattern matching object
(req, res) => {
let n1 = req.data.n1;
let n2 = req.data.n2;
let sum = (n1 + n2);
res.caesarJson({ sum: sum });
}
).add(
{role: 'calculator', operation: 'subtraction'}, // pattern matching object
(req, res) => {
let n1 = req.data.n1;
let n2 = req.data.n2;
let subtraction = (n1 - n2);
res.caesarJson({ subtraction: subtraction });
}
);

It is very interesting to note the following in the above code:

  1. The req object has a data property object attached. This is the data sent & encrypted from the client to the server.
  2. The res object gets a caesarJson( { someJson} ) method. Use this method instead of the express res.json()  method in order to send data encrypted back to the client.
  3. The add method is chainable and you can chain as many endpoints/services as you want.

installPlugin(plugin: Object)

You can now create plugins and extend Caesar.js functionalities by adding extra express middleware and routes.

The main Caesar.js object exports an utility class being pluginBuilder which builds a plugin object.

Example:

const pluginBuilder = require('caesarjs').pluginBuilder;
const server = require('caesarjs').server;
const builder = new pluginBuilder('plugin-id', 'Plugin name', 'My Name', '0.0.1');
builder.addMiddleware( (req, res, next) => {
req.addMyMethod();
next();
});
const plugin = builder.buildPlugin();
new server(3000, {encryptorKey}).installPlugin( plugin )
...

listen()

Once you are ready to start the server run the listen() method.

Example:

new server(3000, optionsObject)
.listen();

A complete working example:

const server = require('./caesar').server;
const encryptorKey = '33a24560-a43b-44cc-b2bc-9cc0de14a093';
new server(3000, {encryptorKey}).add(
{role: 'calculator', operation: 'sum'},
(req, res) => {
let n1 = req.data.n1;
let n2 = req.data.n2;
let sum = (n1 + n2);
res.caesarJson({sum});
})
.add(
{role: 'calculator', operation: 'subtraction'},
(req, res) => {
let n1 = req.data.n1;
let n2 = req.data.n2;
let subtraction = (n1 - n2);
res.caesarJson({subtraction});
})
.listen();

Next section: Server API Middleware Documentation

Leave a Reply

Required fields are marked*

*