Separate out public API registration from xhr and static requests

[epixa]

I propose that we don't expose HTTP directly to plugins. Instead, we expose interfaces for api, xhr, and static. All legacy platform endpoints will go through xhr. If you want to expose a legacy platform endpoint as a public API (e.g. /api), you'll need to create a new platform facade for it.

api

This will mount to /api and will be the definitive place to register public API endpoints. There's an expectation that these will be consumed programmatically outside of Kibana itself. These should only have breaking changes in major versions.

The kbn-xsrf header is enforced for direct access to these endpoints. kbn-version does nothing.

xhr

This will mount to /xhr and will be used to register endpoints that only support being consumed by the Kibana UI. /xhr/api-proxy will proxy through to the public api endpoints, so the Kibana UI will never query /api directly.

The kbn-version header behavior is strictly handled only through these endpoints and is the exclusive xsrf tool enforced on these endpoints as well.

Since these are designed to be used by the Kibana UI alone, there are no concerns about breaking changes.

static

These are static resources, like images.

[kobelb]

Conceptually, I'm on-board with this differentiation and find it to be quite helpful.

Security does have a few public endpoints exposed on /api that we'll need to stay there, so when this change is made we'll either have to move them over to the new platform or provide a "facade" for them in the new platform, I'm interested to hear what this entails.

With regard to the saved object APIs that are exposed at /api and are also publicly available, do we anticipate these being the new "saved object service" that @archanid is working on? The security plugin is currently replacing the SavedObjectClient factory with a secured instance in the old platform, and my fear is that if we switch these APIs to use the new service that we're going to be exposing an unsecured version. The spaces plugin will be wrapping the SavedObjectClient in a similar manner for spaces, which will put this plugin in a similar position.

[epixa]

We'll need to build in facades for all of the APIs documented here, which I assume will soon include security: https://www.elastic.co/guide/en/kibana/master/api.html. It's important that users of those endpoints don't notice this sort of change at all.

With regard to the saved object APIs that are exposed at /api and are also publicly available, do we anticipate these being the new "saved object service" that @archanid is working on? The security plugin is currently replacing the SavedObjectClient factory with a secured instance in the old platform, and my fear is that if we switch these APIs to use the new service that we're going to be exposing an unsecured version. The spaces plugin will be wrapping the SavedObjectClient in a similar manner for spaces, which will put this plugin in a similar position.

This particular proposal shouldn't affect the saved object client at all. Any saved object client exposed through the new platform needs to handle all the security stuff you're adding regardless of whether this proposal proceeds or not.

[epixa]

This change would make it much easier to address #6021

[mshustov]

@joshdover comment from #40623

APIs registered by plugins could benefit from having an explicit difference between public and internal APIs.

• Public APIs are stable across minor releases, provide an OpenAPI spec, are documented publicly, and are exposed to other plugins via a JS client.
• Internal APIs are specific to a plugin and do not provide any stability guarantees.

Additionally, these two types of APIs could have different URL prefixes. For example:

• Public API, registered by pluginA: /api/pluginA/myRoute
• Internal API, registered by pluginA: /internal/pluginA/myRoute

Benefits:

• The explicitness of this difference would help both Kibana devs and 3rd party devs understand the guarantees of a given API.
• Accidental breakage of a public API would be more obvious.
• We can require OpenAPI specs for public APIs to help improve documentation and to generate API clients for various languages.