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 all commits
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
7 changes: 7 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,13 @@ 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?">
<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.

</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