APX (pronounced 'apex') is a non-opinionated, pluggable, modern API server designed to serve multiple communication mediums. The core APX plugins rely on popular community packages such as express, kue, socket.io, winston, object-manage to make configuration and two-way communication a breeze.
APX is built to be test friendly out of the box and comes with a testing
mode in the configuration that will use mock services and increase testing speed.
Well we have evaluated and contributed to several other API servers and just kept running into deficiencies, such as failure to use a popular library and not light-weight enough.
Thus, we created APX. It's light-weight, uses lots of modern packages, and wires them all together in an extensible stateful environment.
APX can be used homogeneously or through our generator.
$ npm install apx
app.js
var apx = require('apx')
apx.once('ready',function(){
console.log('APX is ready!')
})
//pass options and configure
apx.start({
config: ['config.json'],
tasks: ['tasks/*.js'],
initializers: ['apx-kue','apx-mongoose']
translators: ['apx-express']
winston: {file: 'foo.log'}
})
Our generator is a yeoman generator instance that will scaffold your entire API server.
//install the generator
$ npm install generator-apx
//scaffold the initial app
$ yo apx
//scaffold a new action (with test)
$ yo apx:action <name>
//scaffold a new helper (with test)
$ yo apx:helper <name>
//scaffold a new initializer
$ yo apx:initializer <name>
//scaffold a new model
$ yo apx:model <name>
//scaffold a new service (with test)
$ yo apx:service <name>
//scaffold a new test (with test)
$ yo apx:task <name>
//scaffold a new translator
$ yo apx:translator <name>
APX consists of several well-known idioms
Actions are the bread and butter of an API server they serve all requests and build responses. Actions are also in charge of firing non-periodic tasks and utilizing services.
Helpers do not get loaded by the APX loading service however helpers
are meant to be common modules that assist actions and tasks. Generally
these are libraries that augment the req,res variables.
Initializers get executed when the server starts up and are only executed once. These are useful for setting up database connections and loading additional items into the environment.
Middleware is inspired by the idea of Connect Middleware and uses the same principle format.
Middleware is executed before actions are fired and is passed the Request and Response objects for augmentation.
Middleware is also the prescribed location to setup authentication handlers.
Models are optional, but since using models to store data has become so common it seems silly not to support them in context and generators. Models do not get loaded by the APX framework, but can be added during an initializer or per action or task.
Services are just libraries that are treated as singletons. Services should be used to maintain in-memory information, and/or provide access to data providers. Models are services but services are not necessarily models.
Tasks are jobs which are run either periodically or scheduled to run by an action. Tasks are considered headless and while they consume request data. They do not provide response data. They can, however, log using winston.
In other frameworks these are sometimes called "servers". Translators are the
middleware that consumes connections and produce generic Request and Response
objects. An example of a translator would be an express HTTP server.
All parts of the structure are implemented in plugins. APX follows a simple plugin format that is similar in all parts of user space. The main APX package only provides the plugin loader and depends on plugins to add functionality to the system. This allows APX to be non-opinionated.
There are a couple common verbs used in plugins.
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of task' //verbose description for generating maps
exports.run = function(apx,req,res,next){} //code to be executed by apx and fire the next(err) at the end
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of model' //verbose description for generating maps
exports.module = {} //object exported by the helper can also be a constructor
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of initializer' //verbose description for generating maps
exports.start = function(apx,next){} //code to be executed to start the initializer, firing next(err) at the end
exports.stop = function(apx,next){} //code to be executed to stop the initializer, firing next(err) at the end
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of middleware' //verbose description for generating maps
exports.run = function(apx,req,res,next){} //constructor function with a prototype for instantiation
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of model' //verbose description for generating maps
exports.module = {} //model object created by desired database software
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of service' //verbose description for generating maps
exports.module = function(){} //constructor function with a prototype for instantiation
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of action or task' //verbose description for generating maps
exports.start = function(apx,next){} //code to be executed to start the translator, firing next(err) at the end
exports.stop = function(apx,next){} //code to be executed to stop the translator, firing next(err) at the end
exports.name = 'name' //should be concise and match the file name
exports.description = 'description of task' //verbose description for generating maps
exports.run = function(apx,req,next){} //code to be executed by apx and fire the next(err) at the end
Clustering in APX is a breeze. Simply use cluster-master
Here is a quick example
app.js
var apx = require('./apx')
apx.once('ready',function(apx){
console.log('APX is ready!',apx)
})
apx.start({
cwd: __dirname + '/app',
config: ['config.json'],
initializers: ['apx-kue'],
tasks: ['tasks/*.js'],
translators: ['apx-express-socket.io']
express: {
port: 3000
}
})
server.js
var clusterMaster = require('cluster-master')
clusterMaster({
exec: 'app.js',
env: {NODE_ENV: 'production'},
repl: {address: '127.0.0.1', port: 3002}
})
To start the cluster simply run
$ node server
APX is an EventEmitter and will emit various actions during its lifecycle that can be used to hook for additional functionality.
NOTE The event emitter for APX is a singleton so be careful when
registering events as they may get fired by more than one instance. Thus,
its important to use the once operator on a lot of one-off events. Then
use the dead event to re-arm.
Fired each time the readyState of the system changes.
var apx = require('apx')
apx.on('readyStateChange',function(readyState){
console.log('APX changed ready state to ' + readyState)
})
The following ready states are supported.
Fired any time an error occurs.
var apx = require('apx')
apx.on('error',function(err){
console.log('APX had an error',err)
})
Fired when configuration and init is completed
var apx = require('apx')
apx.on('ready',function(inst){
console.log('APX is ready',instance)
})
The instance after init is passed to the event.
Fired after shutdown has been completed.
var apx = require('apx')
apx.on('dead',function(inst){
console.log('APX has died',instance)
})
The instance after shutdown is passed to the event.
Fired before running an action.
var apx = require('apx')
apx.on('runActionBefore',function(action){
console.log('APX action before',action)
})
The action object is passed to the event.
Fired after running an action.
var apx = require('apx')
apx.on('runActionAfter',function(action){
console.log('APX action after',action)
})
The action object is passed to the event.
Fired before running a task.
var apx = require('apx')
apx.on('runTaskBefore',function(task){
console.log('APX task before',task)
})
The task object is passed to the event.
Fired after running a task.
var apx = require('apx')
apx.on('runTaskAfter',function(task){
console.log('APX task after',task)
})
The task object is passed to the event.
NOTE the instance is destroyed after this event.
APX uses object-manage to load and manage configuration data.
This also means the APX instance emits the events from object-manage see below.
testingfalseTesting mode will use fakeredis as much as possible and will not start listening on any ports. However it will still offer a full featured environment for writing tests. Testing mode will also not start Kue which should not be needed to test tasks.
cwd''The current working directory is used when loading actions, services, and tasks.
initializers[]An array of globs or objects or absolute file paths. That should be executed when the server is started.
tasks[]An array of globs or objects or absolute file paths. That will resolve to tasks.
This must be provided at config time to they can be loaded into Kue and scheduled if needed.
translators[]An array of globs or objects or absolute file paths. That will resolve to translators that should be started when the server is started
The lifecycle functions control how APX is started, stopped and configured.
Pass configuration parameters and instantiate the library. Does not start initializers or translators.
apx.setup({
cwd: __dirname
})
Starts the APX server by starting initializers and translators. Once that is compelte
it fires the ready event which is passed the instance of APX.
apx.setup({
cwd: __dirname
})
apx.start()
//or for more convenience
apx.start({
cwd: __dirname
})
Note If no object is passed to start and setup has not been called APX will
throw an exception Tried to start APX without setting it up
Stops the APX server by stopping initializers and translators. Once that is complete
it fires the dead event and destroys the instance.
apx.once('dead',function(){
console.log('APX is now dead')
})
apx.once('ready',function(){
apx.stop()
})
apx.start({cwd: __dirname})
Restart the APX server by stopping initializers and translators and then restarting them.
Stop will fire the dead event.
Start will fire the ready event.
apx.on('dead',function(){
console.log('APX is now dead')
})
apx.on('ready',function(){
console.log('APX is now ready')
})
apx.once('ready',function(){
apx.restart()
})
apx.start({cwd: __dirname})
Reference to the Apx constructor and its prototype. Useful for overriding prototypes before startup.
console.log(apx.Apx.prototype.readyState) //0
The current instance of APX is stored here. This can be use for mocking testing and passing the instance instead of having APX do it manually.
var initializer = require('apx-mongoose')
initializer.start(apx.instance,function(){
console.log('Manually started apx-mongoose')
})
Note the instance will be null by default when APX has either yet to be started or after being stopped.
new Apx the returned object is now an event emitter'use strict'; statements to all files and removed testing init fileonReady has been removed see README for eventsRequest.data and Response.data as references to the managed objects.job object instead of job.dataFAQs
A scalable, extensible, modular API Server
The npm package apx receives a total of 0 weekly downloads. As such, apx popularity was classified as not popular.
We found that apx demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.
Security News
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.
Security News
CISOs are racing to adopt AI for cybersecurity, but hurdles in budgets and governance may leave some falling behind in the fight against cyber threats.