Write an Application #

Kuzzle is fully extensible like any framework. This extensibility is available through the development of an application.

Several classes and methods are available to developers so that they can develop their new business functionalities.

The Backend class #

The Backend class is the entrypoint of any Kuzzle application.

First we need to instantiate it with an application name:

import { Backend } from 'kuzzle';

const app = new Backend('playground');

An application has two phases: setup and runtime. The classes and methods that can be used depend on the phase the application is in.

Register new features #

When the application is in the setup phase, it exposes methods allowing to register new features to Kuzzle, such as:

• controllers: extend the API
• pipes: modify the API behavior
• hooks: execute asynchronous processing
• plugins: add whole set of features

Example: Registering a new Controller with the Backend.controller.register method

// Before application startup
app.controller.register('greeting', {
  actions: {
    sayHello: {
      handler: async request => {
        return `Hello, ${request.input.args.name}`;
      }
    }
  }
});

Once the features have been registered, it is possible to start our Kuzzle application with the Backend.start method.

We will see in detail how to add controllers and pipes in the next chapters of this guide.

Interact with the application #

Once the application has started, methods to interact with it become available.

In particular, those methods make it possible to:

• Use the Embedded SDK to execute API actions
• Trigger Events
• Log Messages
• And much more!

Example: Use the Embedded SDK to create an index after startup with the index.create method

app.start()
  .then(async () => {
    // Interact with Kuzzle API to create a new index if it does not already exist
    if (! await app.sdk.index.exists('nyc-open-data')) {
      await app.sdk.index.create('nyc-open-data');
    }
  })
  .catch(console.error);

Embedded SDK #

In order to use the API actions, Kuzzle exposes an EmbeddedSDK instance through the Backend class.

You can access it through the Backend.sdk property.

Example: Create a new document by using the document.create method

// After application startup

// [...]

// Creates a document
await app.sdk.document.create('nyc-open-data', 'yellow-taxi', {
  name: 'Aschen',
  age: 27
});

The low level query method can also be used to send custom requests to the Kuzzle API.

Example: Execute a custom controller action with the query method

// After application startup

// [...]

// Execute a custom controller action
await app.sdk.query({
  controller: 'greeting',
  action: 'sayHello',
  name: 'Aschen'
});

Complete example #

import { Backend } from 'kuzzle';

// Instantiate an application
const app = new Backend('playground');

// Now we can register features

// Register a new controller
app.controller.register('greeting', {
  actions: {
    sayHello: {
      handler: async request => {
        return `Hello, ${request.input.args.name}`
      }
    }
  }
});

// Start the application
app.start()
  .then(async () => {
    // Now we can interact with Kuzzle API

    // Interact with Kuzzle API to creates a new index if it does not exists
    if (! await app.sdk.index.exists('nyc-open-data')) {
      await app.sdk.index.create('nyc-open-data');
    }
  })
  .catch(console.error);