Opensearch dashboards.httpservicesetup
Home > opensearch-dashboards > HttpServiceSetup
HttpServiceSetup interface
OpenSearch Dashboards 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
@osd/config-schema
package to create a schema to validate the requestparams
,query
, andbody
. Every incoming request will be validated against the created schema. If validation failed, the request is rejected with400
status andBad request
error without calling the route's handler. To opt out of validating the request, specifyfalse
.
import { schema, TypeOf } from '@osd/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 validatedparams
,query
,body
. Andresponse
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 generate500 Server error
response and log error details for further investigation. See below for returning custom error responses.
const handler = async (context: RequestHandlerContext, request: OpenSearchDashboardsRequest, 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 '@osd/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 |
---|---|---|
auth | HttpAuth | Auth status. See HttpAuth |
basePath | IBasePath | Access or manipulate the OpenSearch Dashboards 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 OpenSearch Dashboards. |
getServerInfo | () => HttpServerInfo | Provides common information about the running http server. |
registerAuth | (handler: AuthenticationHandler) => void | To define custom authentication and/or authorization mechanism for incoming requests. |
registerOnPostAuth | (handler: OnPostAuthHandler) => void | To define custom logic after Auth interceptor did make sure a user has access to the requested resource. |
registerOnPreAuth | (handler: OnPreAuthHandler) => void | To define custom logic to perform for incoming requests before the Auth interceptor performs a check that user has access to requested resources. |
registerOnPreResponse | (handler: OnPreResponseHandler) => void | To define custom logic to perform for the server response. |
registerOnPreRouting | (handler: OnPreRoutingHandler) => void | To define custom logic to perform for incoming requests before server performs a route lookup. |
registerRouteHandlerContext | <T extends keyof RequestHandlerContext>(contextName: T, provider: RequestHandlerContextProvider<T>) => RequestHandlerContextContainer | Register a context provider for a route handler. |