Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[dev-docs] Adds section explaining internal and public APIs #195840

Merged
merged 2 commits into from
Oct 11, 2024
Merged

[dev-docs] Adds section explaining internal and public APIs #195840

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d298c6
adds more info to the versioning http apis dev docs for internal vs p…
TinaHeiligers Oct 10, 2024
b5c4b7d
Handle PR review
TinaHeiligers Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions dev_docs/tutorials/versioning_http_apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?">

<DocCallOut >

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


</DocCallOut></DocAccordion>

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
Expand Down