Client API Documentation

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

Getting Started

If you have not already done so please 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 Client API Documentation

Caesar.js client 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.

You must make sure the following points are satisfied:

  • The server & client versions are the same. If you are using client v.0.0.5 to connect to server v.0.0.4 then an error will be thrown.
  • Both server & client must run in same mode (i.e. HTTPS or HTTP)

 

The Client API Documentation Methods

Constructor (host:string, port: integer, options: object)

The constructor takes 3 arguments in the following order:

  • Host (string) – This is the caesar.js server’s host you would like to connect to
  • Port (integer) – This is the port the caesar.js server you would like to connect to is running 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 client = require('caesarjs').client;
const encryptorKey = '33a24560-a43b-44cc-b2bc-9cc0de14a093';
new client('localhost', 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 server. This is used to encrypt/decrypt data sent to or from the client/server. It must be a string of at least 16 characters long.
  • ca (optional) – This is the client root certificate authority needed to run the client securely in HTTPS protocol and to enable as well mutual certificate authentication with the server.
  • clientId (optional) – This is an ID you can assign to the client. If you omit this setting the client will work out an ID itself (based on the architecture/hosting it runs on). The ID will be used by the client to work out stats for end-points usage by each client.

Example running the client on HTTP protocol:

const clientOptions = {
encryptorKey: '33a24560-a43b-44cc-b2bc-9cc0de14a093'
};

Example running the client securely with the HTTPS protocol:

const clientOptions = {
encryptorKey: '33a24560-a43b-44cc-b2bc-9cc0de14a093',
ca: fs.readFileSync(path.join(__dirname, 'path', 'to', 'chain.pem'))
};

init()

The init method allows to connect to the server and if the two entities establish the encryptor keys are the same then the server will pass back metadata about available endpoints back to the client

The init method returns a promise. If the operation is performed successfully then a new instance of the client is returned.

For example:

new client('localhost', 3000, {encryptorKey})
.init()
.then( (client) => {
// do something with 'client' i.e. make a call to the server
})

call( patternMatchingObject: object, dataToSendToEndpoint: Object)

The call method allows to consume one endpoint defined within the server. It takes 2 arguments in the following order:

  1. A pattern matching object to locate the endpoint one wants to use
  2. An optional object to send data to an endpoint

It returns a Promise with a response object containing the data sent back from the server.

For example:

let cclient = null;
new client('localhost', 3000, {encryptorKey})
.init()
.then( (client) => {
cclient = client;
return cclient.call({role: 'calculator', operation: 'sum'}, {n1: 10, n2: 10});
}).then( (resp) => {
console.log('SUM', resp);
});

Built-in server end-points

Server Stats

This endpoint is already built in on the server side and so you will need to call the call method  with the following matching pattern:

{ role: 'stats', cmd: 'getServerStats'}

Example:

client.call({ role: 'stats', cmd: 'getServerStats'})
.then( (stats) => {
console.log('stats');
});

This will return specific server endpoint usage by the specific client. For example:

[ { clientId: 'client-1',
count: 1,
patternObject: {},
path: '/get-user-routes' },
{ clientId: 'client-1',
count: 1,
patternObject: { role: 'calculator', operation: 'sum' },
path: '/user-route/6e85fea2-f839-406b-a503-8a8294252779' },
{ clientId: 'client-1',
count: 2,
patternObject: { role: 'calculator', operation: 'subtraction' },
path: '/user-route/76a5d6ae-9ca7-432d-8b2a-2b4e6f7d5385' },
{ clientId: 'client-1',
count: 1,
patternObject: { role: 'stats', cmd: 'getServerStats' },
path: '/user-route/98fb7976-b4f7-4318-83ee-50c9edcf87dc' } ]

Server Metrics

By calling the following endpoint you will get detailed performance metrics about a specific endpoint. You must supply a pattern object to locate metrics for a particular end-point.

Use the following pattern matcher:

{ role: 'stats', cmd: 'getServerMetrics'}, {patternObject: <patternMatcherObject>}

This will return the last performance metrics of the last 10 calls for the endpoint associated to the patternObject provided.

If you need to increase the number of metrics results set the ‘numberOfResults’ optional data variable.

 

For example:

client.call({ role: 'stats', cmd: 'getServerMetrics'}, {patternObject: {role: 'calculator', operation: 'subtraction'}, numberOfResults: 20 } )
.then( (stats) => {
console.log('stats');
});

The response is something like the following:

[ { seconds: 0,
nanoseconds: 866714,
startTime: 1499728878715,
endTime: 1499728878715,
time: 0.001,
path: '/user-route/6c266b1c-7a58-44ab-9de7-8dde9b45c648',
patternObject: { role: 'calculator', operation: 'subtraction' } },
{ seconds: 0,
nanoseconds: 662329,
startTime: 1499728878726,
endTime: 1499728878727,
time: 0.001,
path: '/user-route/6c266b1c-7a58-44ab-9de7-8dde9b45c648',
patternObject: { role: 'calculator', operation: 'subtraction' } } ]

Finally you can get the number of overall daily calls to all your endpoints combined by using the following pattern matcher:

{ role: 'stats', cmd: 'getTodayCalls'}

For example:

cclient.call({ role: 'stats', cmd: 'getTodayCalls'});

Next section: Client API Documentation

Leave a Reply

Required fields are marked*

*