[dev-docs] Adds section explaining internal and public APIs #195840
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
TinaHeiligers
added
Team:Core
|
Pinging @elastic/kibana-core (Team:Core) |
TinaHeiligers
added
backport:skip
jloleysens
approved these changes
Oct 11, 2024
There was a problem hiding this comment.
Looks great @TinaHeiligers , thanks for improving this documentation!
|
|
||
| **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. |
There was a problem hiding this comment.
I wonder if we should avoid mentioning how to bypass entirely 😅 , I guess eventually most people will figure it out, but I don't want to make it sound like it's OK to bypass it.
| @@ -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. | |||
| </DocCallOut> | |||
|
|
|||
| <DocAccordion buttonContent="FAQ: What is the difference between an internal and a public HTTP API?" color="warning"> | |||
There was a problem hiding this comment.
nit: imo not sure this is a warning level callout, maybe info?
Suggested change
| <DocAccordion buttonContent="FAQ: What is the difference between an internal and a public HTTP API?" color="warning"> | |
| <DocAccordion buttonContent="FAQ: What is the difference between an internal and a public HTTP API?"> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Part of https://github.com/elastic/kibana-team/issues/1044
The tutorial on versioned HTTP APIs mentions internal and public routes and doesn't define what that means for Kibana's HTTP APIs. This PR adds a brief explanation and links to where devs can find more details on the restriction.