@axway/api-builder-runtime/apidoc/arrow.js

/**
 * @class APIBuilder
 * The top-level module for managing APIBuilder services.
 *
 * An APIBuilder service is a Node.js server that runs in the API Runtime Services.
 * To create a server, load the APIBuilder module, then use the APIBuilder constructor to create an
 * APIBuilder instance and invoke its {@link #start start() method}.
 *
 *     var APIBuilder = require('@axway/api-builder-runtime'),
 *         server = new APIBuilder();
 *
 *     // Add event listeners or invoke APIs on the APIBuilder instance
 * 	   var myModel = APIBuilder.createModel('foo', {...});
 *     server.addModel(myModel);
 *
 *     server.on('starting', function () {
 * 	       server.logger.trace('Starting server...');
 *     });
 *
 *     server.start();
 *
 * ### Components
 *
 * An API Builder service is comprised of several components. You can either define the
 * components using JavaScript files placed in specific directories, which are automatically loaded
 * when creating an API Builder instance, or programmatically create components after initializing
 * an API Builder instance.
 *
 * For information about the structure of API Builder services, see
 * [API Builder guides](https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/api_builder.html).
 *
 * #### Express and Third-Party Middleware
 *
 * API Builder uses Express for its web framework. By default, API Builder creates an Express app
 * instance when creating an API Builder instance, then binds its API endpoints to the app instance.
 * You can access the Express app instance using the `app` property of the API Builder instance,
 * then invoke [Express API calls](http://expressjs.com/4x/api.html) on the app instance.
 *
 *     server.app.all('/api/*', function (req, res, next) {
 * 	       req.server.logger.info('Intercepted the request!');
 * 	       next();
 *     });
 *
 * Do not pass the error code to the response object's `send()` method. Use the `status()` method
 * instead. If you pass a number value to the `send()` method, an error will be thrown.
 *
 *     // Throws an error
 *     res.send(500);
 *
 *     // Invoke the following methods instead.
 *     res.status(500).send('Uh oh. Something bad happened.');
 *
 * API Builder also loads the body-parser, cookie-parser and busboy modules to provide additional
 * parsing capabilities as well as the compression module.
 *
 * For Express template engines, API Builder uses ejs, handlebars, marked and react modules.
 * Access the template engines using the {@link APIBuilder.Middleware} API.
 *
 * #### Connectors
 *
 * {@link APIBuilder.Connector Connectors} allow an API Builder service to access data stored
 * in an external source.  Connectors are structured like API Builder service where they have
 * their own models, dependencies and configuration files.
 *
 * You can either use an existing connector or create your own connector.
 *
 * #### Models
 *
 * {@link APIBuilder.Model Models} provide an interface for the API Builder service to access
 * data.  By default, the service will generate standardized endpoints for a client to access
 * the data from the API Builder service.
 *
 * #### APIs
 *
 * {@link APIBuilder.API APIs} provide a way for a client to access your service, execute custom
 * logic and internally access the service's models, then return data back to the client.
 *
 * Create an API to execute a custom operation with model data.
 *
 * #### Blocks
 *
 * {@link APIBuilder.Block Blocks} are functions that run before or after an API endpoint is
executed. * They can be used to modify the API request, to modify the API response or to execute
common * tasks like audit logging, caching, rate limiting or recording analytics. Multiple blocks
can * be executed before or after an API request. Blocks are optional.
 *
 * #### Webs
 *
 * Webs are endpoints that render HTML to the client.
 * Webs are comprised of routes, renderers, templates and static assets.
 *
 * {@link APIBuilder.Router Routes} provide the endpoint to access the Web and logic to access the
 * {@data.
 *
 * {@link APIBuilderRendererEngine Renderers} (or template engines) apply local data to your
templates * to generate HTML. To access a renderer or create your own renderer, use the {@link
APIBuilder.Middleware} API.
 *
 * Templates are the files you want to render. Place all templates in the `./web/views` folder
 * with an appropriate extension--either `ejs`, `hbs`, `html`, `jsx`, `md` or a custom one that
 * you can define. API Builder selects the renderer engine based on the file extension.
 *
 * Place all assets, such as images, style sheets, static HTML files, etc., in the `./web/public`
 * folder.
 *
 * #### Logger
 *
 * The {@link APIBuilder.Logger} provides a wrapper for
 * [bunyan](https://www.npmjs.com/package/bunyan), a JSON logging utility.  By default, API Builder
 * creates a logger instance, which can be accessed using the `logger` property of the API Builder
 * instance.
 *
 *     server.logger.trace('breadcrumbs...');
 *     server.logger.info('%s %s', key, value);
 *     server.logger.error(err);
 *
 * ### Lifecycle
 *
 * The following sections describe the sequence of events that occur when initializing and starting
 * an API Builder service, then making requests to the server.
 *
 * #### Initialization Sequence
 *
 * When creating a new API Builder instance, the following events occur:
 *
 * 1. Loads the configuration files.
 * 2. Creates an Express app instance unless you pass `loadOnly` as `true` in the constructor.
 * 3. Creates the API Builder Console unless its disabled.
 * 4. Creates a Logger instance.
 * 5. Registers the connectors.
 * 6. Loads the model and block files.
 * 7. Loads API and Web files and binds the endpoints to the Express app instance.
 * 8. Fires the `loaded` event.
 *
 * At this point, you may add event listeners or programmatically add any other API Builder
 * components.
 *
 * #### Startup Sequence
 *
 * After invoking the `start()` method on the API Builder instance:
 *
 * 1. Fires the `starting` event.
 * 2. Registers and binds the model's standardized API endpoints to the Express app instance.
 * 3. Fires the `listening` event.
 * 4. Binds the server to a port.
 * 5. Fires the `listen` event.
 * 6. Fires the `started` event.
 *
 * The client can now make requests to the server.
 *
 * #### Request Sequence
 *
 * When a client makes a request to the API Builder service, API Builder first authenticates the
 * request, then proceeds by making a series of middleware calls, where the `next()` function needs
 * to be called after completing each operation.
 *
 * 1. Authenticate the request. If you are using a custom security plugin, the `validateRequest()`
 *    method is defined.
 * 2. For Models, calls the Connector's `startRequest()`, `loginRequired()` and `login()` methods
 *    if defined.
 * 3. Calls any defined pre-Blocks.
 * 4. Calls the API, Model or Router logic.
 * 5. Calls any defined post-Blocks.
 * 6. For Models, calls the Connector's `endRequest()` method if defined.
 * 7. Fires the `after` event.
 *
 * ### API Builder Middleware Calls
 *
 * Each API Builder middleware call (`action` or `execute` property) is passed the same three
 * objects:
 *
 *  * [Express Request object](http://expressjs.com/4x/api.html#req)
 *  * [Express Response object](http://expressjs.com/4x/api.html#res)
 *  * Middleware function to call next. Always call the `next()` function to execute the next
 *    middleware call in the sequence.
 *
 * In addition to the Express APIs, the request object is also passed a reference to the API Builder
 * instance as the `server` property. Use the instance to invoke APIs, such as accessing
 * model data or invoking an API endpoint. Both the request and response objects are passed a
 * reference to the Logger instance as the `logger` property to log messages.
 *
 * For APIBuilder.API instances, the request and response objects are also passed the `model`
 * and `responseModel` properties, which references the models passed to the API constructor.
 */

/**
 * @constructor
 * Loads the configuration files in the `./conf` folder and initializes an API Builder instance.
 * @param {Object} [config] Additional configuration parameters, which are merged with the
 * configuration files. @param {Boolean} [loadOnly] Set to `true` to only load the API Builder
 * components. Does not create the Express app instance or starts the admin console.
 */

/**
 * @event after
 * Fired after a request completes. The callback will be passed the request and response objects.
 */
/**
 * @event error
 * Fired if an error occurred when setting up the server. The callback will be passed the error
 * object.
 */
/**
 * @event listening
 * Fired before binding the server to a port.
 */
/**
 * @event listen
 * Fired when the server can accept connections.
 */
/**
 * @event loaded
 * Fired after initializing the API Builder instance.
 */
/**
 * @event reloaded
 * Fired after reloading an API Builder component.
 */
/**
 * @event starting
 * Fired when the `start()` method is invoked.
 */
/**
 * @event started
 * Fired when the `start()` method completes.
 */
/**
 * @event stopping
 * Fired when the `stop()` method is invoked.
 */
/**
 * @event stopped
 * Fired when the `stop()` method completes.
 */

/**
 * @method addListener
 * Binds a callback to an event.
 * @static
 * @param {String} name Event name
 * @param {Function} cb Callback function to execute.
 */
/**
 * @method on
 * @alias #static-method-addListener
 * @static
 */
/**
 * @method once
 * Binds an one-time listener to an event.
 * @static
 * @param {String} name Event name
 * @param {Function} cb Callback function to execute.
 */
/**
 * @method removeListener
 * Unbinds a callback from an event.
 * @static
 * @param {String} name Event name
 * @param {Function} cb Callback function to remove.
 */
/**
 * @method removeAllListeners
 * Unbinds all event callbacks for the specified event.
 * @static
 * @param {String} [name] Event name. If omitted, unbinds all event listeners.
 */

/**
 * @property {Array<APIBuilder.API>} apis
 * APIs loaded and added to the instance.
 */
/**
 * @property {Object} app
 * Express app instance.
 */
/**
 * @property {Array<APIBuilder.Block>} blocks
 * Blocks loaded or added to the instance.
 */
/**
 * @property {Object} config
 * Configuration object used to initialize the server instance.
 */
/**
 * @property {Object} express
 * Express module instance.
 * @since 1.1.0
 */
/**
 * @property {Boolean} ignoreDuplicateModels
 * Set to `true` to ignore duplicate models.
 */
/**
 * @property {APIBuilder.Logger} logger
 * Logger instance.
 */
/**
 * @property {APIBuilder.Middleware} middleware
 * Middleware instance.
 */
/**
 * @property {Array<APIBuilder.Model>} models
 * Models loaded or added to the instance.
 */
/**
 * @property {Number} port
 * Port number used by the server instance.
 */
/**
 * @property {Array<APIBuilder.Router>} routes
 * Routes loaded to the instance.
 */