Overview

An event handler is a custom, server-side code which responds to an API event. For every API call Backendless generates two types of events - "before" and "after". The before event is fired before the default logic of the API implementation is executed and the "after" event is triggered right after the default API implementation logic. An event handler can respond to either one of these events. A synchronous (blocking) event handler participates in the API invocation chain and can modify the objects in the chain's flow. For example, the "before" event handlers can modify arguments of the API calls, so the default logic gets the modified objects. Similarly, an "after" handler can modify the return value (or exception) so the client application which made the API request receives the modified value. The diagram below illustrates the flow:

All built-in Backendless services emit the "before" and "after" events for every API call. The only exception to this rule is when an API is invoked from server code (for example in a beforeFind handler your code makes an Update API call). This limitation is in place to prevent infinite recursive invocations which may drain the computing resources.

Consider the following example which is an API event handler for the "beforeCreate" API event. The event is triggered when a client application saves an object into the "Contact" data table:

/**
* @param {Object} req The request object contains information about the request
* @param {Object} req.context The execution context contains an information about application, current user and event
* @param {Contact} req.item An item to create
*
* @returns {Contact|Promise.<Contact>|void} By returning a value you can stop further event propagation and return
*          a specific result to the caller
*/
Backendless.ServerCode.Persistence.beforeCreate('Contact', function(req) {
  //add your code here
});

There are several important design elements in the code snippet:* Backendless.ServerCode.Persistence identifies the service for which the event handler will be injecting itself into the API invocation handling chain. * beforeCreate indicates the event handler will be invoked before the default logic of the create method in the Backendless Data service is executed. * The first argument of the beforeCreate method specifies the "asset" or in this case the name of the data table for which the code will be called.