The Kibana Core APIs for server-side plugins.
A plugin requires a kibana.json file at it's root directory that follows the manfiest schema to define static plugin information required to load the plugin.
A plugin's server/index file must contain a named import, plugin, that implements PluginInitializer which returns an object that implements Plugin.
The plugin integrates with the core system via lifecycle events: setup, start, and stop. In each lifecycle method, the plugin will receive the corresponding core services available (either CoreSetup or CoreStart) and any interfaces returned by dependency plugins' lifecycle method. Anything returned by the plugin's lifecycle method will be exposed to downstream dependencies when their corresponding lifecycle methods are invoked.
| Class | Description |
|---|---|
| ClusterClient | Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via asScoped(...)). |
| ElasticsearchErrorHelpers | Helpers for working with errors returned from the Elasticsearch service.Since the internal data of errors are subject to change, consumers of the Elasticsearch service should always use these helpers to classify errors instead of checking error internals such as body.error.header[WWW-Authenticate] |
| KibanaRequest | Kibana specific abstraction for an incoming request. |
| Router | Provides ability to declare a handler function for a particular path and HTTP request method. Each route can have only one handler functions, which is executed when the route is matched. |
| SavedObjectsErrorHelpers | |
| SavedObjectsSchema | |
| SavedObjectsSerializer | |
| ScopedClusterClient | Serves the same purpose as "normal" ClusterClient but exposes additional callAsCurrentUser method that doesn't use credentials of the Kibana internal user (as callAsInternalUser does) to request Elasticsearch API, but rather passes HTTP headers extracted from the current user request to the API |
| Enumeration | Description |
|---|---|
| AuthStatus | Status indicating an outcome of the authentication. |
| Interface | Description |
|---|---|
| AuthResultParams | Result of an incoming request authentication. |
| AuthToolkit | A tool set defining an outcome of Auth interceptor for incoming request. |
| CallAPIOptions | The set of options that defines how API call should be made and result be processed. |
| ContextSetup | |
| CoreSetup | Context passed to the plugins setup method. |
| CoreStart | Context passed to the plugins start method. |
| CustomHttpResponseOptions | HTTP response parameters for a response with adjustable status code. |
| DiscoveredPlugin | Small container object used to expose information about discovered plugins that may or may not have been started. |
| ElasticsearchError | |
| ElasticsearchServiceSetup | |
| FakeRequest | Fake request object created manually by Kibana plugins. |
| HttpResponseOptions | HTTP response parameters |
| HttpServerSetup | 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. |
| HttpServiceStart | |
| InternalCoreStart | |
| KibanaRequestRoute | Request specific route information exposed to a handler. |
| LegacyRequest | |
| Logger | Logger exposes all the necessary methods to log any type of information and this is the interface used by the logging consumers including plugins. |
| LoggerFactory | The single purpose of LoggerFactory interface is to define a way to retrieve a context-based logger instance. |
| LogMeta | Contextual metadata |
| OnPostAuthToolkit | A tool set defining an outcome of OnPostAuth interceptor for incoming request. |
| OnPreAuthToolkit | A tool set defining an outcome of OnPreAuth interceptor for incoming request. |
| Plugin | The interface that should be returned by a PluginInitializer. |
| PluginInitializerContext | Context that's available to plugins during initialization stage. |
| PluginManifest | Describes the set of required and optional properties plugin can define in its mandatory JSON manifest file. |
| PluginsServiceSetup | |
| PluginsServiceStart | |
| ResponseErrorMeta | Additional metadata to enhance error output or provide error details. |
| RouteConfig | Route specific configuration. |
| RouteConfigOptions | Additional route options. |
| SavedObject | |
| SavedObjectAttributes | The data for a Saved Object is stored in the attributes key as either an object or an array of objects. |
| SavedObjectReference | A reference to another saved object. |
| SavedObjectsBaseOptions | |
| SavedObjectsBulkCreateObject | |
| SavedObjectsBulkGetObject | |
| SavedObjectsBulkResponse | |
| SavedObjectsClientProviderOptions | Options to control the creation of the Saved Objects Client. |
| SavedObjectsClientWrapperOptions | Options passed to each SavedObjectsClientWrapperFactory to aid in creating the wrapper instance. |
| SavedObjectsCreateOptions | |
| SavedObjectsExportOptions | Options controlling the export operation. |
| SavedObjectsFindOptions | |
| SavedObjectsFindResponse | Return type of the Saved Objects find() method.*Note*: this type is different between the Public and Server Saved Objects clients. |
| SavedObjectsImportConflictError | Represents a failure to import due to a conflict. |
| SavedObjectsImportError | Represents a failure to import. |
| SavedObjectsImportMissingReferencesError | Represents a failure to import due to missing references. |
| SavedObjectsImportOptions | Options to control the import operation. |
| SavedObjectsImportResponse | The response describing the result of an import. |
| SavedObjectsImportRetry | Describes a retry operation for importing a saved object. |
| SavedObjectsImportUnknownError | Represents a failure to import due to an unknown reason. |
| SavedObjectsImportUnsupportedTypeError | Represents a failure to import due to having an unsupported saved object type. |
| SavedObjectsMigrationLogger | |
| SavedObjectsMigrationVersion | Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value. |
| SavedObjectsRawDoc | A raw document as represented directly in the saved object index. |
| SavedObjectsResolveImportErrorsOptions | Options to control the "resolve import" operation. |
| SavedObjectsService | |
| SavedObjectsUpdateOptions | |
| SavedObjectsUpdateResponse | |
| SessionStorage | Provides an interface to store and retrieve data across requests. |
| SessionStorageCookieOptions | Configuration used to create HTTP session storage based on top of cookie mechanism. |
| SessionStorageFactory | SessionStorage factory to bind one to an incoming request |
| Variable | Description |
|---|---|
| kibanaResponseFactory | Set of helpers used to create KibanaResponse to form HTTP response on an incoming request. Should be returned as a result of RequestHandler execution. |
| Type Alias | Description |
|---|---|
| APICaller | |
| AuthenticationHandler | |
| AuthHeaders | Auth Headers map |
| ConfigPath | |
| ElasticsearchClientConfig | |
| GetAuthHeaders | Get headers to authenticate a user against Elasticsearch. |
| GetAuthState | Get authentication state for a request. Returned by auth interceptor. |
| Headers | Http request headers to read. |
| HttpResponsePayload | Data send to the client as a response payload. |
| HttpServiceSetup | |
| IsAuthenticated | Return authentication status for a request. |
| KibanaResponseFactory | Creates an object containing request response payload, HTTP headers, error details, and other data transmitted to the client. |
| KnownHeaders | Set of well-known HTTP headers. |
| LifecycleResponseFactory | Creates an object containing redirection or error response with error details, HTTP headers, and other data transmitted to the client. |
| OnPostAuthHandler | |
| OnPreAuthHandler | |
| PluginInitializer | The plugin export at the root of a plugin's server directory should conform to this interface. |
| PluginName | Dedicated type for plugin name/id that is supposed to make Map/Set/Arrays that use it as a key or value more obvious. |
| PluginOpaqueId | |
| RecursiveReadonly | |
| RedirectResponseOptions | HTTP response parameters for redirection response |
| RequestHandler | A function executed when route path matched requested resource path. Request handler is expected to return a result of one of KibanaResponseFactory functions. |
| ResponseError | Error message and optional data send to the client in case of error. |
| RouteMethod | The set of common HTTP methods supported by Kibana routing. |
| SavedObjectAttribute | |
| SavedObjectsClientContract | Saved Objects is Kibana's data persisentence mechanism allowing plugins to use Elasticsearch for storing plugin state.## SavedObjectsClient errorsSince the SavedObjectsClient has its hands in everything we are a little paranoid about the way we present errors back to to application code. Ideally, all errors will be either:1. Caused by bad implementation (ie. undefined is not a function) and as such unpredictable 2. An error that has been classified and decorated appropriately by the decorators in SavedObjectsErrorHelpersType 1 errors are inevitable, but since all expected/handle-able errors should be Type 2 the isXYZError() helpers exposed at SavedObjectsErrorHelpers should be used to understand and manage error responses from the SavedObjectsClient.Type 2 errors are decorated versions of the source error, so if the elasticsearch client threw an error it will be decorated based on its type. That means that rather than looking for error.body.error.type or doing substring checks on error.body.error.reason, just use the helpers to understand the meaning of the error:```js if (SavedObjectsErrorHelpers.isNotFoundError(error)) { // handle 404 }if (SavedObjectsErrorHelpers.isNotAuthorizedError(error)) { // 401 handling should be automatic, but in case you wanted to know }// always rethrow the error unless you handle it throw error; ```### 404s from missing indexFrom the perspective of application code and APIs the SavedObjectsClient is a black box that persists objects. One of the internal details that users have no control over is that we use an elasticsearch index for persistance and that index might be missing.At the time of writing we are in the process of transitioning away from the operating assumption that the SavedObjects index is always available. Part of this transition is handling errors resulting from an index missing. These used to trigger a 500 error in most cases, and in others cause 404s with different error messages.From my (Spencer) perspective, a 404 from the SavedObjectsApi is a 404; The object the request/call was targeting could not be found. This is why #14141 takes special care to ensure that 404 errors are generic and don't distinguish between index missing or document missing.### 503s from missing indexUnlike all other methods, create requests are supposed to succeed even when the Kibana index does not exist because it will be automatically created by elasticsearch. When that is not the case it is because Elasticsearch's action.auto_create_index setting prevents it from being created automatically so we throw a special 503 with the intention of informing the user that their Elasticsearch settings need to be updated.See SavedObjectsErrorHelpers |
| SavedObjectsClientWrapperFactory | Describes the factory used to create instances of Saved Objects Client Wrappers. |