[Discuss] Add NP core.http.route

[jfsiii]

Bringing this discussion from Slack into an issue

Request: Add a function in NP core.http that behaves like hapi’s server.route i.e. accepts a config object (or array of objects)? It needn't be a 1:1 match with the hapi function. Just something that accepts a config object (or array of them) with the basic info needed (method, path, validate, options, handler, etc)

The Integrations Manager plugin is currently using that approach to define routes.

It's also the method shown in the migration guide

kibana/src/core/MIGRATION.md

Lines 463 to 473 in 4de1acf

	// HTTP functionality from core
	core.http.route({ // note: we know routes will be created on core.http
	path: '/api/demo_plugin/search',
	method: 'POST',
	async handler(request) {
	const requestFacade: RequestFacade = {
	headers: request.headers
	};
	search(serverFacade, requestFacade);
	}
	});

This declarative approach is quite nice for authors. They markup the various pieces of the routes, then pass it to a function which does The Right Thing ™️

It also allows a simple data structure to be passed into the plugin which is great for composition and testing.

I think there are many other benefits for both authors and the Platform team, but I'll wait to hear back before going further.

[elasticmachine]

Pinging @elastic/kibana-platform

[jfsiii]

I just saw a recent PR from @elastic/apm-ui which also uses this route+object approach.

[dgieselaar]

@jfsiii I think you need @elastic/apm-ui (elastic/apm is a little too wide in this case as it includes agents/server).

[mshustov]

I'm not opposed to add proposed API, as it more generic, provides declarative API and supports multiple registration.
Kibana HTTP service is meant to be a thin layer between HTTP server and plugins, so I'm inclining towards providing a single way to declare a route handler. If we want to switch to proposed API it's better to do now till plugins start migration.
@elastic/kibana-platform

[jfsiii]

I'm happy to submit a PR if that helps. I'd be sure to get agreement on what the interface should be, how to implement, test, etc before starting. Just let me know.

[rudolf]

@restrry I also like the proposed API and agree that it's better to only expose one way of registering routes.

[joshdover]

I don't have any problems with the proposed API, as long as there's only a single way to register a route, I'm happy.

One slight advantage to the existing API is that we can change the types of the params a bit more easily to better fit the HTTP method. For example, a GET request shouldn't specify any validation schema for it's payload because it should not have one.

In terms of priority, I don't think this is a blocker for anyone, but if there is a strong consensus for the proposed change, then we should do it sooner than later to avoid unnecessary churn.

[jfsiii]

For example, a GET request shouldn't specify any validation schema for it's payload because it should not have one.

I believe we can use a discriminated union since the different types are all based on the value of the method property.

[mshustov]

should be done as a part of #44620
I will attach a link to borrow some ideas from the current discussion.

[jfsiii]

I don't have any problems with the proposed API, as long as there's only a single way to register a route, I'm happy.

This reminds me of the client-side http interface

• http.fetch(path, options): This has an API comparable to window.fetch with the addition of a few custom options, status code error handling, default HTTP header additions, and automatic body parsing resolution for JSON and NDJSON.
• http.get(path, options): The GET-enforced shorthand for http.fetch().
• http.post(path, options): The POST-enforced shorthand for http.fetch().
• http.put(path, options): The PUT-enforced shorthand for http.fetch().
• http.delete(path, options): The DELETE-enforced shorthand for http.fetch().
• http.patch(path, options): The PATCH-enforced shorthand for http.fetch().

I see router.route as analogous to the client-side http.fetch as the underlying/"longhand" function and router[VERB] functions as the parallels to the http[VERB] shorthands.