From 4d298c6bf078e7347958f447cf9bf5a81bea0fa4 Mon Sep 17 00:00:00 2001 From: "Christiane (Tina) Heiligers" Date: Thu, 10 Oct 2024 16:18:23 -0700 Subject: [PATCH 1/2] adds more info to the versioning http apis dev docs for internal vs public routes --- dev_docs/tutorials/versioning_http_apis.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/dev_docs/tutorials/versioning_http_apis.mdx b/dev_docs/tutorials/versioning_http_apis.mdx index 25361ba2ae792..6a4cc16897a7e 100644 --- a/dev_docs/tutorials/versioning_http_apis.mdx +++ b/dev_docs/tutorials/versioning_http_apis.mdx @@ -15,6 +15,17 @@ All Kibana HTTP API developers and maintainers must ensure that past versions of The exact number of past APIs and the length of time they are kept available will vary per use case. Generally, the length of time will be shorter for internal HTTP APIs than for public HTTP APIs. + + + +We only declare HTTP APIs that are stable and reliable as public and keep all development changes behind internal HTTP APIs. Public HTTP APIs are intended for external consumption and are typically garanteed not to change within a major. Internal HTTP APIs may change more frequently, as long as they adhere to the versioning principles outlined in the rest of this doc. + +**How do we prevent external consumers from using internal APIs?** +Access to [internal APIs is restricted](https://github.com/elastic/kibana/pull/193792) behind a configuration setting, `server.restrictInternalApis`. When set to true (the default), external requests without a special internal header or query parameter are blocked. +Of course there are ways of [getting around the restriction](https://github.com/elastic/kibana/pull/195696) but it has to be by choice and not incidental as it has been up to now. + + + Versioned HTTP APIs should hold to the following set of properties. **Note:** how you meet these is properties is up to you. Use the examples provided as a guide. ### 1. Do not directly expose persistence schemas on your HTTP API endpoints From b5c4b7d2c3c5b1e86f865c8d8e67103fe21b3686 Mon Sep 17 00:00:00 2001 From: "Christiane (Tina) Heiligers" Date: Fri, 11 Oct 2024 08:52:11 -0700 Subject: [PATCH 2/2] Handle PR review --- dev_docs/tutorials/versioning_http_apis.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/dev_docs/tutorials/versioning_http_apis.mdx b/dev_docs/tutorials/versioning_http_apis.mdx index 6a4cc16897a7e..390f55be01c45 100644 --- a/dev_docs/tutorials/versioning_http_apis.mdx +++ b/dev_docs/tutorials/versioning_http_apis.mdx @@ -15,14 +15,10 @@ All Kibana HTTP API developers and maintainers must ensure that past versions of The exact number of past APIs and the length of time they are kept available will vary per use case. Generally, the length of time will be shorter for internal HTTP APIs than for public HTTP APIs. - + We only declare HTTP APIs that are stable and reliable as public and keep all development changes behind internal HTTP APIs. Public HTTP APIs are intended for external consumption and are typically garanteed not to change within a major. Internal HTTP APIs may change more frequently, as long as they adhere to the versioning principles outlined in the rest of this doc. - -**How do we prevent external consumers from using internal APIs?** -Access to [internal APIs is restricted](https://github.com/elastic/kibana/pull/193792) behind a configuration setting, `server.restrictInternalApis`. When set to true (the default), external requests without a special internal header or query parameter are blocked. -Of course there are ways of [getting around the restriction](https://github.com/elastic/kibana/pull/195696) but it has to be by choice and not incidental as it has been up to now.