kibana/docs/development/core/server/kibana-plugin-server.httpservicesetup.md

Home > kibana-plugin-server > HttpServiceSetup

HttpServiceSetup interface

Kibana HTTP Service provides own abstraction for work with HTTP stack. Plugins don't have direct access to hapi server and its primitives anymore. Moreover, plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood. This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins. If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs.

Signature:

export interface HttpServiceSetup 

Example

To handle an incoming request in your plugin you should: - Create a Router instance.

const router = httpSetup.createRouter();

• Use @kbn/config-schema package to create a schema to validate the request params, query, and body. Every incoming request will be validated against the created schema. If validation failed, the request is rejected with 400 status and Bad request error without calling the route's handler. To opt out of validating the request, specify false.

import { schema, TypeOf } from '@kbn/config-schema';
const validate = {
  params: schema.object({
    id: schema.string(),
  }),
};

• Declare a function to respond to incoming request. The function will receive request object containing request details: url, headers, matched route, as well as validated params, query, body. And response object instructing HTTP server to create HTTP response with information sent back to the client as the response body, headers, and HTTP status. Unlike, hapi route handler in the Legacy platform, any exception raised during the handler call will generate 500 Server error response and log error details for further investigation. See below for returning custom error responses.

const handler = async (context: RequestHandlerContext, request: KibanaRequest, response: ResponseFactory) => {
  const data = await findObject(request.params.id);
  // creates a command to respond with 'not found' error
  if (!data) return response.notFound();
  // creates a command to send found data to the client and set response headers
  return response.ok({
    body: data,
    headers: {
      'content-type': 'application/json'
    }
  });
}

• Register route handler for GET request to 'path/{id}' path

import { schema, TypeOf } from '@kbn/config-schema';
const router = httpSetup.createRouter();

const validate = {
  params: schema.object({
    id: schema.string(),
  }),
};

router.get({
  path: 'path/{id}',
  validate
},
async (context, request, response) => {
  const data = await findObject(request.params.id);
  if (!data) return response.notFound();
  return response.ok({
    body: data,
    headers: {
      'content-type': 'application/json'
    }
  });
});

Properties

Property	Type	Description
basePath	IBasePath	Access or manipulate the Kibana base path See IBasePath.
createCookieSessionStorageFactory	<T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>>	Creates cookie based session storage factory SessionStorageFactory
createRouter	() => IRouter	Provides ability to declare a handler function for a particular path and HTTP request method.
csp	ICspConfig	The CSP config used for Kibana.
isTlsEnabled	boolean	Flag showing whether a server was configured to use TLS connection.
registerAuth	(handler: AuthenticationHandler) => void	To define custom authentication and/or authorization mechanism for incoming requests.
registerOnPostAuth	(handler: OnPostAuthHandler) => void	To define custom logic to perform for incoming requests.
registerOnPreAuth	(handler: OnPreAuthHandler) => void	To define custom logic to perform for incoming requests.
registerOnPreResponse	(handler: OnPreResponseHandler) => void	To define custom logic to perform for the server response.
registerRouteHandlerContext	<T extends keyof RequestHandlerContext>(contextName: T, provider: RequestHandlerContextProvider<T>) => RequestHandlerContextContainer	Register a context provider for a route handler.