Core
Framework v2.x
2

ControllerDefinition #

Available since 2.8.0

The ControllerDefinition type is used to define new controllers.

This type can be found as the second argument of the Backend.controller.use method or as the Controller.definition property.

/*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
  * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
import { JSONObject } from "kuzzle-sdk";
import { KuzzleRequest } from "../api/request";
/**
  * API controller definition.
  *
  * @example
  * {
  *   actions: {
  *     sayHello: {
  *       handler: async request => `Hello, ${request.input.args.name}`,
  *       http: [{ verb: 'post', path: '/greeting/hello/:name' }]
  *     }
  *   }
  * }
  */
export type ControllerDefinition = {
  /**
    * Definition of controller actions
    *
    * @example
    * {
    *   sayHello: {
    *     handler: async request => `Hello, ${request.input.args.name}`,
    *     http: [{
    *       verb: 'post',
    *       path: '/greeting/hello/:name',
    *       openapi: {
    *         description: "Simply say hello",
    *         responses: {
    *           200: {
    *             description: "Custom greeting",
    *             content: {
    *               "application/json": {
    *                 schema: {
    *                   type: "string",
    *                 }
    *               }
    *             }
    *           }
    *         }
    *       }
    *     }]
    *   }
    * }
    */
  actions: {
    /**
      * Name of the API action
      */
    [action: string]: {
      /**
        * Function handler for incoming requests.
        */
      handler: (request: KuzzleRequest) => Promise<any>;
      /**
        * Declare HTTP routes (optional).
        * Http routes will be auto-generated unless at least one is provided
        * or an empty array is provided.
        */
      http?: HttpRoute[];
    };
  };
};
/**
  * Http route definition
  */
export type HttpRoute = {
  /**
    * HTTP verb.
    */
  verb: "get" | "head" | "post" | "put" | "delete" | "patch" | "options";
  /**
    * Route path.
    * A route starting with `/` will be prefixed by `/_` otherwise the route
    * will be prefixed by `/_/<application-name>/`.
    */
  path: string;
  /**
    * Provide a (openAPI specification v3)[https://swagger.io/specification/#paths-object] for this route.
    * Kuzzle only expect the `paths` object of the specification.
    * When not defined, Kuzzle generate one from the action definition by itself.
    *
    * @example
    * {
    *   description: "Simply say hello",
    *   parameters: [{
    *     in: "path",
    *     name: "name",
    *     schema: {
    *       type: "string"
    *     },
    *     required: true,
    *   }],
    *   responses: {
    *     200: {
    *       description: "Custom greeting",
    *       content: {
    *         "application/json": {
    *           schema: {
    *             type: "string",
    *           }
    *         }
    *       }
    *     }
    *   }
    * }
    */
  openapi?: JSONObject;
};

Example:

import { ControllerDefinition, KuzzleRequest } from 'kuzzle';

const definition: ControllerDefinition = {
  actions: {
    sayHello: {
      handler: async (request: KuzzleRequest) => 'Hello',
      http: [{
        verb: 'post',
        path: 'greeting/sayHello',
        openapi: {
          description: "Simply say hello",
          responses: {
            200: {
              content: {
                "application/json": {
                  schema: {
                    type: "string",
                  }
                }
              }
            }
          }
        }
      }],
    }
  }
};