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

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.

- [x]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
This commit is contained in:
Christiane (Tina) Heiligers 2024-10-11 09:16:47 -07:00 committed by GitHub
parent e5f7739b26
commit cfd9d8d5c2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

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