Skip to content

Commit

Permalink
[dev-docs] Adds section explaining internal and public APIs (#195840)
Browse files Browse the repository at this point in the history
Part of elastic/kibana-team#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
  • Loading branch information
TinaHeiligers authored Oct 11, 2024
1 parent e5f7739 commit cfd9d8d
Showing 1 changed file with 7 additions and 0 deletions.
7 changes: 7 additions & 0 deletions dev_docs/tutorials/versioning_http_apis.mdx
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

0 comments on commit cfd9d8d

Please sign in to comment.