Listeners in order
An event holds listeners that run one after another, each with its own time limit, in the sandbox or on the native process. They read the data in g.req.eventData.
Your code
Events & Listeners
React to API calls with your own listeners, or emit events from any code.
An event runs a list of TypeScript listeners after an API call, or when your code emits it. The caller always gets its response first. Listeners can emit more events, API Maker stops loops for you, and the code that emits an event gets the output of every listener back.
See it live
Step through it, slow it down, or open the full canvas.
api-maker/features/events-managementLive- Events run
- 0in this tour
- Listeners
- 0run in order
- Loops
- 0stopped
- Skipped
- 0not in the list
The response first, then the events. An event can run on every call of an API: generated, schema, custom or system. The caller gets its response first, the event gets that response as its data.
How it works
The response first, then the events.
An event can run on every call of an API: generated, schema, custom or system. The caller gets its response first, the event gets that response as its data.
Listeners run one after another.
Each listener is TypeScript run in the sandbox, with its own timeout. It reads the data in g.req.eventData: send a receipt, update the stock, call any API.
Events can emit events.
Any listener can run another event with g.sys.system.emitEvent. Workflows grow step by step, each step in its own listener.
A loop is stopped at once.
API Maker keeps the chain of events of each call. An event that is already in it is not run again, the caller gets the chain in the error.
Emit an event from any code, or over REST.
Name the listeners to run only those. emitEvent returns the output of each listener. Other systems use the emit-event system API.
What you get
Triggered by any API
Attach an event to generated, schema, custom or system APIs: it runs after every call, with the response as its data.
Emitted from code
g.sys.system.emitEvent(name, data, listeners) runs an event from any code, all its listeners or only the ones you name.
Outputs come back
emitEvent returns the output of each listener that ran, so a custom API can use the result of the workflow it started.
No endless loops
API Maker keeps the chain of events of each call. An event already in the chain is not run again, and the error shows the chain.
From other systems
The emit-event system API runs an event over REST, with the same data and the same choice of listeners.
An example
After an order is placed
The order API answers the shop at once. Then the event order-placed records a notification for the customer, sends the receipt and updates the stock, and a low stock emits stock-low, whose listener orders more from the supplier.
import * as T from 'types';async function main(g: T.IAMGlobal) { const order = g.req.eventData; await g.sys.db.saveSingleOrMultiple({ instance: 'mongodb', database: 'shop', collection: 'notifications', saveData: { customer_id: order.customer_id, text: `Order ${order._id} is paid.` }, });}module.exports = main;import * as T from 'types';async function main(g: T.IAMGlobal) { const order = g.req.body; // Only send-receipt runs : update-stock does not take the stock twice const out = await g.sys.system.emitEvent('order-placed', order, ['send-receipt']); return out.outputArr[0].output; // { listenerName, output } of each listener that ran}module.exports = main;
Good to know
- Events run after the response, so they can not change it. Use a post hook for that.
- Each listener has a time limit in minutes: split long work into several listeners or events.
Questions
Do events slow down my APIs?
No. The response is written first. Events, WebSocket notifications and logs run after it.
Can I run only some listeners of an event?
Yes. Pass their names to g.sys.system.emitEvent or to the emit-event system API. A name that does not exist is an error.
How do I push an event to web and mobile apps?
With WebSockets: apps register for an API or a custom WebSocket event, and g.sys.system.emitEventWS pushes to them.
Learn more
Documentation